{"openapi":"3.1.0","info":{"title":"Helply External Analytics API","version":"1.0.0","description":"Read-only analytics endpoints for Helply chats and messages."},"servers":[{"url":"https://app.helply.com"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ChatSummary":{"type":"object","required":["id","number","created_at","completed_at","state","source","message_count"],"properties":{"id":{"type":"string","format":"uuid"},"number":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"state":{"type":"string","enum":["pending","resolved","escalated"]},"source":{"type":["string","null"]},"message_count":{"type":"integer","minimum":0}}},"ChatMessage":{"type":"object","required":["id","created_at","sender","type","text","escalated"],"properties":{"id":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"sender":{"type":"string"},"type":{"type":"string"},"text":{"type":"string"},"escalated":{"type":["boolean","null"]}}},"ChatDetail":{"allOf":[{"$ref":"#/components/schemas/ChatSummary"},{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}}}}]},"PublicError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"security":[{"bearerAuth":[]}],"paths":{"/api/public/v1/agents/{agent_id}/chats":{"get":{"summary":"List chats","description":"Returns chat summaries only. If no time range is provided, the last 30 days are returned. The maximum allowed window is 183 days.","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"maximum":100,"minimum":1}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"state","in":"query","required":false,"schema":{"type":"string","enum":["pending","resolved","escalated"]}},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"Chat summaries","content":{"application/json":{"schema":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChatSummary"}},"pagination":{"type":"object","required":["next_cursor","has_more","limit"],"properties":{"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"},"limit":{"type":"integer"}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"429":{"description":"Rate limited at 60 requests per 60 seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}},"/api/public/v1/agents/{agent_id}/chats/{chat_id}":{"get":{"summary":"Retrieve a single chat","description":"Returns one chat with all public message fields.","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"chat_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Chat detail","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ChatDetail"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"404":{"description":"Chat not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"429":{"description":"Rate limited at 60 requests per 60 seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}}}}}}