{"openapi":"3.0.3","info":{"title":"chat-agent API","version":"0.1.0"},"servers":[{"url":"https://preview.chat.gortix.com"}],"components":{"schemas":{},"parameters":{}},"paths":{"/api/v1/health":{"get":{"tags":["System"],"summary":"Liveness probe","responses":{"200":{"description":"Service is alive","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"uptimeSeconds":{"type":"number","minimum":0},"timestamp":{"type":"string","format":"date-time"}},"required":["status","uptimeSeconds","timestamp"]},"requestId":{"type":"string","minLength":1}},"required":["data","requestId"]}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"details":{"nullable":true}},"required":["code","message"]},"requestId":{"type":"string","minLength":1}},"required":["error","requestId"]}}}}}}},"/api/v1/ready":{"get":{"tags":["System"],"summary":"Readiness probe","responses":{"200":{"description":"Service is ready","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["ready","not_ready"]},"checks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"status":{"type":"string","enum":["ok","fail"]},"message":{"type":"string","minLength":1}},"required":["name","status"]}},"timestamp":{"type":"string","format":"date-time"}},"required":["status","checks","timestamp"]},"requestId":{"type":"string","minLength":1}},"required":["data","requestId"]}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"details":{"nullable":true}},"required":["code","message"]},"requestId":{"type":"string","minLength":1}},"required":["error","requestId"]}}}},"503":{"description":"Service is not ready","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["ready","not_ready"]},"checks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"status":{"type":"string","enum":["ok","fail"]},"message":{"type":"string","minLength":1}},"required":["name","status"]}},"timestamp":{"type":"string","format":"date-time"}},"required":["status","checks","timestamp"]},"requestId":{"type":"string","minLength":1}},"required":["data","requestId"]}}}}}}},"/api/v1/meta":{"get":{"tags":["System"],"summary":"Runtime metadata","responses":{"200":{"description":"Service metadata","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"service":{"type":"string","minLength":1},"version":{"type":"string","minLength":1},"environment":{"type":"string","enum":["local","preview","production"]},"commitSha":{"type":"string","nullable":true}},"required":["service","version","environment","commitSha"]},"requestId":{"type":"string","minLength":1}},"required":["data","requestId"]}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"details":{"nullable":true}},"required":["code","message"]},"requestId":{"type":"string","minLength":1}},"required":["error","requestId"]}}}}}}},"/api/v1/conversations":{"post":{"tags":["Chat"],"summary":"Create or restore a widget conversation","responses":{"200":{"description":"Conversation snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"conversation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"type":"string","enum":["web-widget","twilio-whatsapp"]},"state":{"type":"string","minLength":1},"userId":{"type":"string","nullable":true,"format":"uuid"},"sessionId":{"type":"string","format":"uuid"},"isReturningUser":{"type":"boolean"},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"sequence":{"type":"integer","minimum":0,"exclusiveMinimum":true},"actor":{"type":"string","enum":["assistant","user","status","admin"]},"text":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"fileName":{"type":"string","minLength":1},"contentType":{"type":"string","minLength":1},"sizeBytes":{"type":"integer","minimum":0}},"required":["id","fileName","contentType","sizeBytes"]}},"createdAt":{"type":"string","format":"date-time"},"channel":{"type":"string","enum":["customer","admin_user","admin_agent","agent_internal","system"]},"visibility":{"type":"string","enum":["public","internal"]},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["id","sequence","actor","text","attachments","createdAt"]}},"context":{"type":"object","properties":{"runtimeMode":{"type":"string","enum":["legacy","agent"],"default":"legacy"},"mode":{"type":"string","nullable":true,"enum":["new","edit"]},"goal":{"type":"string","nullable":true,"enum":["bookings","leads","support","sales"]},"surfaceIntent":{"type":"string","nullable":true,"enum":["general_chat","build_new_site","edit_existing_site","ambiguous"],"default":null},"mobileNumber":{"type":"string","nullable":true},"otpRequestedAt":{"type":"string","nullable":true,"format":"date-time"},"verificationState":{"type":"object","properties":{"mobileNumber":{"type":"string","nullable":true},"otpRequestedAt":{"type":"string","nullable":true,"format":"date-time"},"otpVerified":{"type":"boolean"},"verifiedUserId":{"type":"string","nullable":true,"format":"uuid"}},"default":{"mobileNumber":null,"otpRequestedAt":null,"otpVerified":false,"verifiedUserId":null},"required":["mobileNumber","otpRequestedAt","otpVerified","verifiedUserId"]},"hasAcceptedTerms":{"type":"boolean"},"draftAssetCount":{"type":"integer","minimum":0},"draftSourceCount":{"type":"integer","minimum":0},"agentSessionId":{"type":"string","nullable":true,"default":null},"activeProjectId":{"type":"string","nullable":true},"activeProjectDisplayName":{"type":"string","nullable":true},"publicProgressState":{"type":"string","enum":["chatting","collecting_intent","awaiting_otp","collecting_details","reviewing","building_preview","preview_ready","failed","live"],"default":"collecting_intent"},"currentBlockerClass":{"type":"string","nullable":true,"enum":["business","technical"],"default":null},"currentBlockerReason":{"type":"string","nullable":true,"default":null},"awaitingApproval":{"type":"string","enum":["none","otp","terms","template","publish_confirmation","publish_pin","admin"],"default":"none"},"currentObjectiveSummary":{"type":"string","nullable":true,"default":null},"currentNode":{"type":"string","nullable":true,"default":null},"lastSuccessfulNode":{"type":"string","nullable":true,"default":null},"lastFailedNode":{"type":"string","nullable":true,"default":null},"checkpointVersion":{"type":"integer","minimum":0,"default":0},"hasPendingPinSetup":{"type":"boolean"},"pendingJob":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["preview","publish"]},"jobId":{"type":"string","minLength":1},"createdAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["pending","failed","completed"]},"errorMessage":{"type":"string","nullable":true}},"required":["type","jobId","createdAt","status","errorMessage"]},"failureClass":{"type":"string","nullable":true,"enum":["business_recoverable","technical_failure"]},"blockedReason":{"type":"string","nullable":true},"blockedSince":{"type":"string","nullable":true,"format":"date-time"},"blockedDetails":{"type":"string","nullable":true},"adminVisible":{"type":"boolean"},"interview":{"type":"object","properties":{"projectName":{"type":"string","nullable":true,"default":null},"businessType":{"type":"string","nullable":true,"default":null},"serviceSummary":{"type":"string","nullable":true,"default":null},"targetAudience":{"type":"string","nullable":true,"default":null},"notes":{"type":"string","nullable":true,"default":null},"toneKeywords":{"type":"array","items":{"type":"string"},"default":[]},"bannedKeywords":{"type":"array","items":{"type":"string"},"default":[]},"buildReadinessNotes":{"type":"string","nullable":true,"default":null},"contactMethod":{"type":"string","nullable":true,"enum":["whatsapp","contact_form","both"],"default":null},"contactEmail":{"type":"string","nullable":true,"default":null},"contactSubjectTemplate":{"type":"string","nullable":true,"default":null},"contactSuccessMessage":{"type":"string","nullable":true,"default":null},"whatsappNumber":{"type":"string","nullable":true,"default":null},"whatsappNumberConfirmed":{"type":"boolean","nullable":true,"default":null},"whatsappDefaultMessage":{"type":"string","nullable":true,"default":null},"whatsappPlacement":{"type":"array","items":{"type":"string"},"default":[]},"location":{"type":"string","nullable":true,"default":null},"desiredChanges":{"type":"string","nullable":true,"default":null},"missingSlots":{"type":"array","items":{"type":"string"},"default":[]},"skippedOptionalSlots":{"type":"array","items":{"type":"string"},"default":[]}}},"intervention":{"type":"object","properties":{"mode":{"type":"string","enum":["assist","takeover"]},"requestedAt":{"type":"string","nullable":true,"format":"date-time"},"operatorEmail":{"type":"string","nullable":true},"lastSuggestedQuestions":{"type":"array","items":{"type":"string"}},"resumeState":{"type":"string","nullable":true}},"required":["mode","requestedAt","operatorEmail","lastSuggestedQuestions","resumeState"]}},"required":["mode","goal","mobileNumber","otpRequestedAt","hasAcceptedTerms","draftAssetCount","draftSourceCount","activeProjectId","activeProjectDisplayName","hasPendingPinSetup","pendingJob","failureClass","blockedReason","blockedSince","blockedDetails","adminVisible","interview","intervention"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","channel","state","userId","sessionId","isReturningUser","messages","context","createdAt","updatedAt"]},"sessionToken":{"type":"string","minLength":1}},"required":["conversation","sessionToken"]},"requestId":{"type":"string","minLength":1}},"required":["data","requestId"]}}}}}}},"/api/v1/conversations/{conversationId}/events":{"get":{"tags":["Chat"],"summary":"Poll new conversation events","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversationId","in":"path"}],"responses":{"200":{"description":"Conversation events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"conversation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"type":"string","enum":["web-widget","twilio-whatsapp"]},"state":{"type":"string","minLength":1},"userId":{"type":"string","nullable":true,"format":"uuid"},"sessionId":{"type":"string","format":"uuid"},"isReturningUser":{"type":"boolean"},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"sequence":{"type":"integer","minimum":0,"exclusiveMinimum":true},"actor":{"type":"string","enum":["assistant","user","status","admin"]},"text":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"fileName":{"type":"string","minLength":1},"contentType":{"type":"string","minLength":1},"sizeBytes":{"type":"integer","minimum":0}},"required":["id","fileName","contentType","sizeBytes"]}},"createdAt":{"type":"string","format":"date-time"},"channel":{"type":"string","enum":["customer","admin_user","admin_agent","agent_internal","system"]},"visibility":{"type":"string","enum":["public","internal"]},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["id","sequence","actor","text","attachments","createdAt"]}},"context":{"type":"object","properties":{"runtimeMode":{"type":"string","enum":["legacy","agent"],"default":"legacy"},"mode":{"type":"string","nullable":true,"enum":["new","edit"]},"goal":{"type":"string","nullable":true,"enum":["bookings","leads","support","sales"]},"surfaceIntent":{"type":"string","nullable":true,"enum":["general_chat","build_new_site","edit_existing_site","ambiguous"],"default":null},"mobileNumber":{"type":"string","nullable":true},"otpRequestedAt":{"type":"string","nullable":true,"format":"date-time"},"verificationState":{"type":"object","properties":{"mobileNumber":{"type":"string","nullable":true},"otpRequestedAt":{"type":"string","nullable":true,"format":"date-time"},"otpVerified":{"type":"boolean"},"verifiedUserId":{"type":"string","nullable":true,"format":"uuid"}},"default":{"mobileNumber":null,"otpRequestedAt":null,"otpVerified":false,"verifiedUserId":null},"required":["mobileNumber","otpRequestedAt","otpVerified","verifiedUserId"]},"hasAcceptedTerms":{"type":"boolean"},"draftAssetCount":{"type":"integer","minimum":0},"draftSourceCount":{"type":"integer","minimum":0},"agentSessionId":{"type":"string","nullable":true,"default":null},"activeProjectId":{"type":"string","nullable":true},"activeProjectDisplayName":{"type":"string","nullable":true},"publicProgressState":{"type":"string","enum":["chatting","collecting_intent","awaiting_otp","collecting_details","reviewing","building_preview","preview_ready","failed","live"],"default":"collecting_intent"},"currentBlockerClass":{"type":"string","nullable":true,"enum":["business","technical"],"default":null},"currentBlockerReason":{"type":"string","nullable":true,"default":null},"awaitingApproval":{"type":"string","enum":["none","otp","terms","template","publish_confirmation","publish_pin","admin"],"default":"none"},"currentObjectiveSummary":{"type":"string","nullable":true,"default":null},"currentNode":{"type":"string","nullable":true,"default":null},"lastSuccessfulNode":{"type":"string","nullable":true,"default":null},"lastFailedNode":{"type":"string","nullable":true,"default":null},"checkpointVersion":{"type":"integer","minimum":0,"default":0},"hasPendingPinSetup":{"type":"boolean"},"pendingJob":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["preview","publish"]},"jobId":{"type":"string","minLength":1},"createdAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["pending","failed","completed"]},"errorMessage":{"type":"string","nullable":true}},"required":["type","jobId","createdAt","status","errorMessage"]},"failureClass":{"type":"string","nullable":true,"enum":["business_recoverable","technical_failure"]},"blockedReason":{"type":"string","nullable":true},"blockedSince":{"type":"string","nullable":true,"format":"date-time"},"blockedDetails":{"type":"string","nullable":true},"adminVisible":{"type":"boolean"},"interview":{"type":"object","properties":{"projectName":{"type":"string","nullable":true,"default":null},"businessType":{"type":"string","nullable":true,"default":null},"serviceSummary":{"type":"string","nullable":true,"default":null},"targetAudience":{"type":"string","nullable":true,"default":null},"notes":{"type":"string","nullable":true,"default":null},"toneKeywords":{"type":"array","items":{"type":"string"},"default":[]},"bannedKeywords":{"type":"array","items":{"type":"string"},"default":[]},"buildReadinessNotes":{"type":"string","nullable":true,"default":null},"contactMethod":{"type":"string","nullable":true,"enum":["whatsapp","contact_form","both"],"default":null},"contactEmail":{"type":"string","nullable":true,"default":null},"contactSubjectTemplate":{"type":"string","nullable":true,"default":null},"contactSuccessMessage":{"type":"string","nullable":true,"default":null},"whatsappNumber":{"type":"string","nullable":true,"default":null},"whatsappNumberConfirmed":{"type":"boolean","nullable":true,"default":null},"whatsappDefaultMessage":{"type":"string","nullable":true,"default":null},"whatsappPlacement":{"type":"array","items":{"type":"string"},"default":[]},"location":{"type":"string","nullable":true,"default":null},"desiredChanges":{"type":"string","nullable":true,"default":null},"missingSlots":{"type":"array","items":{"type":"string"},"default":[]},"skippedOptionalSlots":{"type":"array","items":{"type":"string"},"default":[]}}},"intervention":{"type":"object","properties":{"mode":{"type":"string","enum":["assist","takeover"]},"requestedAt":{"type":"string","nullable":true,"format":"date-time"},"operatorEmail":{"type":"string","nullable":true},"lastSuggestedQuestions":{"type":"array","items":{"type":"string"}},"resumeState":{"type":"string","nullable":true}},"required":["mode","requestedAt","operatorEmail","lastSuggestedQuestions","resumeState"]}},"required":["mode","goal","mobileNumber","otpRequestedAt","hasAcceptedTerms","draftAssetCount","draftSourceCount","activeProjectId","activeProjectDisplayName","hasPendingPinSetup","pendingJob","failureClass","blockedReason","blockedSince","blockedDetails","adminVisible","interview","intervention"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","channel","state","userId","sessionId","isReturningUser","messages","context","createdAt","updatedAt"]},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"sequence":{"type":"integer","minimum":0,"exclusiveMinimum":true},"actor":{"type":"string","enum":["assistant","user","status","admin"]},"text":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"fileName":{"type":"string","minLength":1},"contentType":{"type":"string","minLength":1},"sizeBytes":{"type":"integer","minimum":0}},"required":["id","fileName","contentType","sizeBytes"]}},"createdAt":{"type":"string","format":"date-time"},"channel":{"type":"string","enum":["customer","admin_user","admin_agent","agent_internal","system"]},"visibility":{"type":"string","enum":["public","internal"]},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["id","sequence","actor","text","attachments","createdAt"]}}},"required":["conversation","messages"]},"requestId":{"type":"string","minLength":1}},"required":["data","requestId"]}}}},"401":{"description":"Invalid or expired session","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"details":{"nullable":true}},"required":["code","message"]},"requestId":{"type":"string","minLength":1}},"required":["error","requestId"]}}}},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"details":{"nullable":true}},"required":["code","message"]},"requestId":{"type":"string","minLength":1}},"required":["error","requestId"]}}}}}}},"/api/v1/openapi.json":{"get":{"tags":["Documentation"],"summary":"OpenAPI specification document","responses":{"200":{"description":"OpenAPI specification","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"nullable":true}}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"details":{"nullable":true}},"required":["code","message"]},"requestId":{"type":"string","minLength":1}},"required":["error","requestId"]}}}}}}},"/api/v1/docs":{"get":{"tags":["Documentation"],"summary":"Swagger UI documentation","responses":{"301":{"description":"Redirects to the Swagger UI page at /api/v1/docs/"},"500":{"description":"Internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"details":{"nullable":true}},"required":["code","message"]},"requestId":{"type":"string","minLength":1}},"required":["error","requestId"]}}}}}}},"/robots.txt":{"get":{"tags":["Discovery"],"summary":"Robots directives","responses":{"200":{"description":"robots.txt","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"details":{"nullable":true}},"required":["code","message"]},"requestId":{"type":"string","minLength":1}},"required":["error","requestId"]}}}}}}},"/sitemap.xml":{"get":{"tags":["Discovery"],"summary":"Sitemap","responses":{"200":{"description":"XML sitemap","content":{"application/xml":{"schema":{"type":"string"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"details":{"nullable":true}},"required":["code","message"]},"requestId":{"type":"string","minLength":1}},"required":["error","requestId"]}}}}}}},"/llms.txt":{"get":{"tags":["Discovery"],"summary":"LLM discovery document","responses":{"200":{"description":"llms.txt","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"details":{"nullable":true}},"required":["code","message"]},"requestId":{"type":"string","minLength":1}},"required":["error","requestId"]}}}}}}}}}