{"openapi":"3.1.0","info":{"title":"HelpoSoft API","version":"1.0.0","description":"Unified ticket, conversation and contact API for HelpoSoft integrations."},"servers":[{"url":"https://helposoft.com/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/me":{"get":{"summary":"Get the API workspace","responses":{"200":{"description":"Workspace"}}}},"/tickets":{"get":{"summary":"List tickets","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["open","pending","resolved","closed"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Ticket list"}}},"post":{"summary":"Create a ticket","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketCreate"}}}},"responses":{"201":{"description":"Created"},"422":{"description":"Validation error"}}}},"/tickets/{id}":{"get":{"summary":"Get a ticket and its messages","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Ticket"},"404":{"description":"Not found"}}}},"/tickets/{id}/messages":{"post":{"summary":"Add a ticket message","parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"sender_type":{"type":"string","enum":["customer","agent"]},"private":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Created"}}}},"/tickets/{id}/update":{"post":{"summary":"Update ticket status or priority","parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","pending","resolved","closed"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]}}}}}},"responses":{"200":{"description":"Updated"}}}},"/conversations":{"get":{"summary":"List live-chat conversations","responses":{"200":{"description":"Conversation list"}}}},"/conversations/{id}":{"get":{"summary":"Get a conversation and messages","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Conversation"}}}},"/conversations/{id}/messages":{"post":{"summary":"Add a conversation message","parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"sender_type":{"type":"string","enum":["visitor","agent"]}}}}}},"responses":{"201":{"description":"Created"}}}},"/contacts":{"get":{"summary":"List contacts","responses":{"200":{"description":"Contact list"}}},"post":{"summary":"Create or update a contact","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"responses":{"201":{"description":"Contact"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"HelpoSoft API key"}},"parameters":{"Id":{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}},"schemas":{"Contact":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"external_id":{"type":"string"},"metadata":{"type":"object","additionalProperties":true}}},"TicketCreate":{"type":"object","required":["subject","message"],"properties":{"subject":{"type":"string","maxLength":255},"message":{"type":"string","maxLength":20000},"priority":{"type":"string","enum":["low","normal","high","urgent"],"default":"normal"},"channel":{"type":"string","enum":["api","wordpress","whmcs","email","chat"]},"contact":{"$ref":"#/components/schemas/Contact"},"metadata":{"type":"object","additionalProperties":true}}}}}}