{"openapi":"3.1.0","info":{"title":"zxn.uk Chat API","version":"1.0.0","description":"Agent REST API, visitor (widget) API and agent interop for zxn.uk Chat. MCP lives at /mcp, A2A at /a2a/{public_key}."},"servers":[{"url":"https://chat.zxn.uk"}],"paths":{"/v1/me":{"get":{"summary":"The signed-in user and their workspaces","tags":["Account"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"$ref":"#/$defs/User"},"workspaces":{"type":"array","items":{"$ref":"#/$defs/Workspace"}}},"required":["user","workspaces"],"$defs":{"User":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"}},"required":["id","email","name","avatar_url","created_at"]},"Workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"role":{"type":"string","enum":["owner","admin","agent"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"counts":{"type":"object","properties":{"open":{"type":"number"},"unassigned":{"type":"number"},"mine":{"type":"number"}},"required":["open","unassigned","mine"]}},"required":["id","name","slug","role","created_at","counts"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]},"patch":{"summary":"Update my profile","tags":["Account"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/User","$defs":{"User":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"}},"required":["id","email","name","avatar_url","created_at"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80}}}}}},"security":[{"bearer":[]}]}},"/v1/whoami":{"get":{"summary":"Who the credential is: a user, or an API key and its workspace and scopes","tags":["Account"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]}},"/v1/devices":{"post":{"summary":"Register a push device (upsert by token)","tags":["Account"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["ios","android"]},"push_token":{"type":"string","minLength":8,"maxLength":4096},"app_version":{"type":"string","maxLength":40},"locale":{"type":"string","maxLength":20}},"required":["platform","push_token"]}}}},"security":[{"bearer":[]}]}},"/v1/devices/{id}":{"delete":{"summary":"Forget a push device","tags":["Account"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]}},"/v1/workspaces":{"post":{"summary":"Create a workspace (caller becomes owner)","tags":["Workspaces"],"parameters":[],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/Workspace","$defs":{"Workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"role":{"type":"string","enum":["owner","admin","agent"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"counts":{"type":"object","properties":{"open":{"type":"number"},"unassigned":{"type":"number"},"mine":{"type":"number"}},"required":["open","unassigned","mine"]}},"required":["id","name","slug","role","created_at","counts"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80}},"required":["name"]}}}},"security":[{"bearer":[]}]}},"/v1/workspaces/{ws}":{"get":{"summary":"Get a workspace","tags":["Workspaces"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/Workspace","$defs":{"Workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"role":{"type":"string","enum":["owner","admin","agent"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"counts":{"type":"object","properties":{"open":{"type":"number"},"unassigned":{"type":"number"},"mine":{"type":"number"}},"required":["open","unassigned","mine"]}},"required":["id","name","slug","role","created_at","counts"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]},"patch":{"summary":"Rename a workspace","tags":["Workspaces"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/Workspace","$defs":{"Workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"role":{"type":"string","enum":["owner","admin","agent"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"counts":{"type":"object","properties":{"open":{"type":"number"},"unassigned":{"type":"number"},"mine":{"type":"number"}},"required":["open","unassigned","mine"]}},"required":["id","name","slug","role","created_at","counts"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80}},"required":["name"]}}}},"security":[{"bearer":[]}]},"delete":{"summary":"Delete a workspace (owner only)","tags":["Workspaces"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]}},"/v1/workspaces/{ws}/members":{"get":{"summary":"List members","tags":["Team"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/$defs/Member"},"$defs":{"Member":{"type":"object","properties":{"user_id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":"string"},"role":{"type":"string","enum":["owner","admin","agent"]},"status":{"type":"string","enum":["online","away","offline"]},"avatar_url":{"type":["string","null"]},"last_seen_at":{"type":["string","null"]},"notify":{"type":"object","properties":{"new_conversation":{"type":"boolean"},"every_message":{"type":"boolean"},"assigned_only":{"type":"boolean"}},"required":["new_conversation","every_message","assigned_only"]}},"required":["user_id","name","email","role","status","avatar_url","last_seen_at"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]}},"/v1/workspaces/{ws}/members/me":{"patch":{"summary":"My availability and notification settings","tags":["Team"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/Member","$defs":{"Member":{"type":"object","properties":{"user_id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":"string"},"role":{"type":"string","enum":["owner","admin","agent"]},"status":{"type":"string","enum":["online","away","offline"]},"avatar_url":{"type":["string","null"]},"last_seen_at":{"type":["string","null"]},"notify":{"type":"object","properties":{"new_conversation":{"type":"boolean"},"every_message":{"type":"boolean"},"assigned_only":{"type":"boolean"}},"required":["new_conversation","every_message","assigned_only"]}},"required":["user_id","name","email","role","status","avatar_url","last_seen_at"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["online","away"]},"display_name":{"type":"string","minLength":1,"maxLength":80},"notify":{"type":"object","properties":{"new_conversation":{"type":"boolean"},"every_message":{"type":"boolean"},"assigned_only":{"type":"boolean"},"quiet_hours":{"anyOf":[{"type":"object","properties":{"start":{"type":"string","pattern":"^\\d\\d:\\d\\d$"},"end":{"type":"string","pattern":"^\\d\\d:\\d\\d$"},"tz":{"type":"string","maxLength":60}},"required":["start","end"]},{"type":"null"}]}}}}}}}},"security":[{"bearer":[]}]}},"/v1/workspaces/{ws}/members/{user_id}":{"patch":{"summary":"Change a member role","tags":["Team"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/Member","$defs":{"Member":{"type":"object","properties":{"user_id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":"string"},"role":{"type":"string","enum":["owner","admin","agent"]},"status":{"type":"string","enum":["online","away","offline"]},"avatar_url":{"type":["string","null"]},"last_seen_at":{"type":["string","null"]},"notify":{"type":"object","properties":{"new_conversation":{"type":"boolean"},"every_message":{"type":"boolean"},"assigned_only":{"type":"boolean"}},"required":["new_conversation","every_message","assigned_only"]}},"required":["user_id","name","email","role","status","avatar_url","last_seen_at"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["owner","admin","agent"]}},"required":["role"]}}}},"security":[{"bearer":[]}]},"delete":{"summary":"Remove a member (or leave)","tags":["Team"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]}},"/v1/workspaces/{ws}/invites":{"get":{"summary":"Pending invites","tags":["Team"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"},"expires_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","email","role","expires_at","created_at"]}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]},"post":{"summary":"Invite someone by email (sends a join link and code)","tags":["Team"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"},"expires_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","email","role","expires_at","created_at"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"role":{"default":"agent","type":"string","enum":["admin","agent"]}},"required":["email"]}}}},"security":[{"bearer":[]}]}},"/v1/invites/accept":{"post":{"summary":"Accept an invite","tags":["Team"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/Workspace","$defs":{"Workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"role":{"type":"string","enum":["owner","admin","agent"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"counts":{"type":"object","properties":{"open":{"type":"number"},"unassigned":{"type":"number"},"mine":{"type":"number"}},"required":["open","unassigned","mine"]}},"required":["id","name","slug","role","created_at","counts"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":8,"maxLength":200}},"required":["token"]}}}},"security":[{"bearer":[]}]}},"/v1/workspaces/{ws}/sites":{"get":{"summary":"List sites","tags":["Sites"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/$defs/Site"},"$defs":{"Site":{"type":"object","properties":{"id":{"type":"string"},"public_key":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"allowed_origins":{"type":"array","items":{"type":"string"}},"appearance":{"type":"object","properties":{"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"position":{"type":"string","enum":["right","left"]},"greeting":{"type":"string","maxLength":300},"launcher_label":{"type":"string","maxLength":40},"logo_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"theme":{"type":"string","enum":["auto","light","dark"]},"team_name":{"type":"string","maxLength":60}},"required":["accent","position","greeting","launcher_label","logo_url","theme","team_name"]},"ai":{"type":"object","properties":{"mode":{"type":"string","enum":["until_human","off"]},"persona":{"type":"string","maxLength":1000},"max_replies":{"type":"integer","minimum":1,"maximum":50}},"required":["mode","persona","max_replies"]},"hours":{"type":"object","properties":{"tz":{"type":"string","maxLength":60},"days":{"type":"object","propertyNames":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]},"additionalProperties":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string","pattern":"^\\d\\d:\\d\\d$"},{"type":"string","pattern":"^\\d\\d:\\d\\d$"}],"items":false,"minItems":2,"maxItems":2}},"required":["mon","tue","wed","thu","fri","sat","sun"]},"offline_message":{"type":"string","maxLength":300}},"required":["tz","days","offline_message"]},"knowledge_text":{"type":"string"},"knowledge_urls":{"type":"array","items":{"type":"string"}},"collect_email":{"type":"string","enum":["off","optional","required"]},"installed_at":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"}},"required":["id","public_key","name","domain","allowed_origins","appearance","ai","hours","knowledge_text","knowledge_urls","collect_email","installed_at","created_at"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}],"x-scope":"sites:read"},"post":{"summary":"Create a site (defaults filled)","tags":["Sites"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/Site","$defs":{"Site":{"type":"object","properties":{"id":{"type":"string"},"public_key":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"allowed_origins":{"type":"array","items":{"type":"string"}},"appearance":{"type":"object","properties":{"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"position":{"type":"string","enum":["right","left"]},"greeting":{"type":"string","maxLength":300},"launcher_label":{"type":"string","maxLength":40},"logo_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"theme":{"type":"string","enum":["auto","light","dark"]},"team_name":{"type":"string","maxLength":60}},"required":["accent","position","greeting","launcher_label","logo_url","theme","team_name"]},"ai":{"type":"object","properties":{"mode":{"type":"string","enum":["until_human","off"]},"persona":{"type":"string","maxLength":1000},"max_replies":{"type":"integer","minimum":1,"maximum":50}},"required":["mode","persona","max_replies"]},"hours":{"type":"object","properties":{"tz":{"type":"string","maxLength":60},"days":{"type":"object","propertyNames":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]},"additionalProperties":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string","pattern":"^\\d\\d:\\d\\d$"},{"type":"string","pattern":"^\\d\\d:\\d\\d$"}],"items":false,"minItems":2,"maxItems":2}},"required":["mon","tue","wed","thu","fri","sat","sun"]},"offline_message":{"type":"string","maxLength":300}},"required":["tz","days","offline_message"]},"knowledge_text":{"type":"string"},"knowledge_urls":{"type":"array","items":{"type":"string"}},"collect_email":{"type":"string","enum":["off","optional","required"]},"installed_at":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"}},"required":["id","public_key","name","domain","allowed_origins","appearance","ai","hours","knowledge_text","knowledge_urls","collect_email","installed_at","created_at"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"domain":{"default":"","type":"string","maxLength":253}},"required":["name"]}}}},"security":[{"bearer":[]}],"x-scope":"sites:write"}},"/v1/workspaces/{ws}/sites/{site_id}":{"get":{"summary":"Get a site","tags":["Sites"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"site_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/Site","$defs":{"Site":{"type":"object","properties":{"id":{"type":"string"},"public_key":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"allowed_origins":{"type":"array","items":{"type":"string"}},"appearance":{"type":"object","properties":{"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"position":{"type":"string","enum":["right","left"]},"greeting":{"type":"string","maxLength":300},"launcher_label":{"type":"string","maxLength":40},"logo_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"theme":{"type":"string","enum":["auto","light","dark"]},"team_name":{"type":"string","maxLength":60}},"required":["accent","position","greeting","launcher_label","logo_url","theme","team_name"]},"ai":{"type":"object","properties":{"mode":{"type":"string","enum":["until_human","off"]},"persona":{"type":"string","maxLength":1000},"max_replies":{"type":"integer","minimum":1,"maximum":50}},"required":["mode","persona","max_replies"]},"hours":{"type":"object","properties":{"tz":{"type":"string","maxLength":60},"days":{"type":"object","propertyNames":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]},"additionalProperties":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string","pattern":"^\\d\\d:\\d\\d$"},{"type":"string","pattern":"^\\d\\d:\\d\\d$"}],"items":false,"minItems":2,"maxItems":2}},"required":["mon","tue","wed","thu","fri","sat","sun"]},"offline_message":{"type":"string","maxLength":300}},"required":["tz","days","offline_message"]},"knowledge_text":{"type":"string"},"knowledge_urls":{"type":"array","items":{"type":"string"}},"collect_email":{"type":"string","enum":["off","optional","required"]},"installed_at":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"}},"required":["id","public_key","name","domain","allowed_origins","appearance","ai","hours","knowledge_text","knowledge_urls","collect_email","installed_at","created_at"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}],"x-scope":"sites:read"},"patch":{"summary":"Update a site (any field except ids)","tags":["Sites"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"site_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/Site","$defs":{"Site":{"type":"object","properties":{"id":{"type":"string"},"public_key":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"allowed_origins":{"type":"array","items":{"type":"string"}},"appearance":{"type":"object","properties":{"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"position":{"type":"string","enum":["right","left"]},"greeting":{"type":"string","maxLength":300},"launcher_label":{"type":"string","maxLength":40},"logo_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"theme":{"type":"string","enum":["auto","light","dark"]},"team_name":{"type":"string","maxLength":60}},"required":["accent","position","greeting","launcher_label","logo_url","theme","team_name"]},"ai":{"type":"object","properties":{"mode":{"type":"string","enum":["until_human","off"]},"persona":{"type":"string","maxLength":1000},"max_replies":{"type":"integer","minimum":1,"maximum":50}},"required":["mode","persona","max_replies"]},"hours":{"type":"object","properties":{"tz":{"type":"string","maxLength":60},"days":{"type":"object","propertyNames":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]},"additionalProperties":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string","pattern":"^\\d\\d:\\d\\d$"},{"type":"string","pattern":"^\\d\\d:\\d\\d$"}],"items":false,"minItems":2,"maxItems":2}},"required":["mon","tue","wed","thu","fri","sat","sun"]},"offline_message":{"type":"string","maxLength":300}},"required":["tz","days","offline_message"]},"knowledge_text":{"type":"string"},"knowledge_urls":{"type":"array","items":{"type":"string"}},"collect_email":{"type":"string","enum":["off","optional","required"]},"installed_at":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"}},"required":["id","public_key","name","domain","allowed_origins","appearance","ai","hours","knowledge_text","knowledge_urls","collect_email","installed_at","created_at"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"domain":{"type":"string","maxLength":253},"allowed_origins":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":300}},"appearance":{"type":"object","properties":{"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"position":{"type":"string","enum":["right","left"]},"greeting":{"type":"string","maxLength":300},"launcher_label":{"type":"string","maxLength":40},"logo_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"theme":{"type":"string","enum":["auto","light","dark"]},"team_name":{"type":"string","maxLength":60}}},"ai":{"type":"object","properties":{"mode":{"type":"string","enum":["until_human","off"]},"persona":{"type":"string","maxLength":1000},"max_replies":{"type":"integer","minimum":1,"maximum":50}}},"hours":{"type":"object","properties":{"tz":{"type":"string","maxLength":60},"days":{"type":"object","propertyNames":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]},"additionalProperties":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string","pattern":"^\\d\\d:\\d\\d$"},{"type":"string","pattern":"^\\d\\d:\\d\\d$"}],"items":false,"minItems":2,"maxItems":2}},"required":["mon","tue","wed","thu","fri","sat","sun"]},"offline_message":{"type":"string","maxLength":300}}},"knowledge_text":{"type":"string","maxLength":60000},"knowledge_urls":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":500,"format":"uri"}},"collect_email":{"type":"string","enum":["off","optional","required"]}}}}}},"security":[{"bearer":[]}],"x-scope":"sites:write"},"delete":{"summary":"Delete a site and its conversations","tags":["Sites"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"site_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}],"x-scope":"sites:write"}},"/v1/workspaces/{ws}/sites/{site_id}/install":{"get":{"summary":"Install snippet and links","tags":["Sites"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"site_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}],"x-scope":"sites:read"}},"/v1/workspaces/{ws}/conversations":{"get":{"summary":"List conversations, newest activity first","tags":["Conversations"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"view","in":"query","required":false,"schema":{"default":"all","type":"string","enum":["mine","unassigned","all","closed"]}},{"name":"site_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/$defs/Conversation"}},"next_cursor":{"type":["string","null"]}},"required":["items","next_cursor"],"$defs":{"Conversation":{"type":"object","properties":{"id":{"type":"string"},"site_id":{"type":"string"},"site_name":{"type":"string"},"channel":{"type":"string","enum":["web","a2a","api"]},"status":{"type":"string","enum":["open","pending","closed"]},"assignee":{"anyOf":[{"type":"object","properties":{"user_id":{"type":"string"},"name":{"type":["string","null"]}},"required":["user_id","name"]},{"type":"null"}]},"ai_state":{"type":"string","enum":["on","off"]},"subject":{"type":["string","null"]},"visitor":{"$ref":"#/$defs/Visitor"},"agent_peer":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name"]},{"type":"null"}]},"last_message":{"type":"object","properties":{"preview":{"type":"string"},"author":{"type":"string"},"at":{"type":"string","description":"ISO-8601 UTC timestamp"}},"required":["preview","author","at"]},"unread":{"type":"number"},"page_url":{"type":["string","null"]},"page_title":{"type":["string","null"]},"referrer":{"type":["string","null"]},"utm":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"rating":{"type":["number","null"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"closed_at":{"type":["string","null"]},"seq":{"type":"number"}},"required":["id","site_id","site_name","channel","status","assignee","ai_state","subject","visitor","agent_peer","last_message","unread","page_url","page_title","referrer","utm","rating","created_at","closed_at","seq"]},"Visitor":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"display_name":{"type":"string"},"country":{"type":["string","null"]},"city":{"type":["string","null"]},"tz":{"type":["string","null"]},"locale":{"type":["string","null"]},"device":{"type":["string","null"]},"first_seen_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"last_seen_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"current_page":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"title":{"type":["string","null"]}},"required":["url","title"]},{"type":"null"}]},"custom":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","name","email","display_name","country","city","tz","locale","device","first_seen_at","last_seen_at","current_page","custom"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}],"x-scope":"conversations:read"}},"/v1/workspaces/{ws}/conversations/{cv}":{"get":{"summary":"Get a conversation","tags":["Conversations"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"cv","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/Conversation","$defs":{"Conversation":{"type":"object","properties":{"id":{"type":"string"},"site_id":{"type":"string"},"site_name":{"type":"string"},"channel":{"type":"string","enum":["web","a2a","api"]},"status":{"type":"string","enum":["open","pending","closed"]},"assignee":{"anyOf":[{"type":"object","properties":{"user_id":{"type":"string"},"name":{"type":["string","null"]}},"required":["user_id","name"]},{"type":"null"}]},"ai_state":{"type":"string","enum":["on","off"]},"subject":{"type":["string","null"]},"visitor":{"$ref":"#/$defs/Visitor"},"agent_peer":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name"]},{"type":"null"}]},"last_message":{"type":"object","properties":{"preview":{"type":"string"},"author":{"type":"string"},"at":{"type":"string","description":"ISO-8601 UTC timestamp"}},"required":["preview","author","at"]},"unread":{"type":"number"},"page_url":{"type":["string","null"]},"page_title":{"type":["string","null"]},"referrer":{"type":["string","null"]},"utm":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"rating":{"type":["number","null"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"closed_at":{"type":["string","null"]},"seq":{"type":"number"}},"required":["id","site_id","site_name","channel","status","assignee","ai_state","subject","visitor","agent_peer","last_message","unread","page_url","page_title","referrer","utm","rating","created_at","closed_at","seq"]},"Visitor":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"display_name":{"type":"string"},"country":{"type":["string","null"]},"city":{"type":["string","null"]},"tz":{"type":["string","null"]},"locale":{"type":["string","null"]},"device":{"type":["string","null"]},"first_seen_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"last_seen_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"current_page":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"title":{"type":["string","null"]}},"required":["url","title"]},{"type":"null"}]},"custom":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","name","email","display_name","country","city","tz","locale","device","first_seen_at","last_seen_at","current_page","custom"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}],"x-scope":"conversations:read"},"patch":{"summary":"Change status, assignee or turn the AI off","tags":["Conversations"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"cv","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/Conversation","$defs":{"Conversation":{"type":"object","properties":{"id":{"type":"string"},"site_id":{"type":"string"},"site_name":{"type":"string"},"channel":{"type":"string","enum":["web","a2a","api"]},"status":{"type":"string","enum":["open","pending","closed"]},"assignee":{"anyOf":[{"type":"object","properties":{"user_id":{"type":"string"},"name":{"type":["string","null"]}},"required":["user_id","name"]},{"type":"null"}]},"ai_state":{"type":"string","enum":["on","off"]},"subject":{"type":["string","null"]},"visitor":{"$ref":"#/$defs/Visitor"},"agent_peer":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name"]},{"type":"null"}]},"last_message":{"type":"object","properties":{"preview":{"type":"string"},"author":{"type":"string"},"at":{"type":"string","description":"ISO-8601 UTC timestamp"}},"required":["preview","author","at"]},"unread":{"type":"number"},"page_url":{"type":["string","null"]},"page_title":{"type":["string","null"]},"referrer":{"type":["string","null"]},"utm":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"rating":{"type":["number","null"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"closed_at":{"type":["string","null"]},"seq":{"type":"number"}},"required":["id","site_id","site_name","channel","status","assignee","ai_state","subject","visitor","agent_peer","last_message","unread","page_url","page_title","referrer","utm","rating","created_at","closed_at","seq"]},"Visitor":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"display_name":{"type":"string"},"country":{"type":["string","null"]},"city":{"type":["string","null"]},"tz":{"type":["string","null"]},"locale":{"type":["string","null"]},"device":{"type":["string","null"]},"first_seen_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"last_seen_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"current_page":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"title":{"type":["string","null"]}},"required":["url","title"]},{"type":"null"}]},"custom":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","name","email","display_name","country","city","tz","locale","device","first_seen_at","last_seen_at","current_page","custom"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["open","pending","closed"]},"assignee_id":{"type":["string","null"]},"ai_state":{"type":"string","const":"off"}}}}}},"security":[{"bearer":[]}],"x-scope":"conversations:write"}},"/v1/workspaces/{ws}/conversations/{cv}/messages":{"get":{"summary":"Message history (newest last) or catch-up","tags":["Messages"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"cv","in":"path","required":true,"schema":{"type":"string"}},{"name":"before_seq","in":"query","required":false,"schema":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},{"name":"after_seq","in":"query","required":false,"schema":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/$defs/Message"}},"has_more":{"type":"boolean"}},"required":["items","has_more"],"$defs":{"Message":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":"string"},"seq":{"type":"number"},"author":{"type":"string","enum":["visitor","agent","ai","system","note"]},"author_id":{"type":["string","null"]},"author_name":{"type":["string","null"]},"author_avatar_url":{"type":["string","null"]},"body":{"type":"string"},"meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"client_id":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"edited_at":{"type":["string","null"]}},"required":["id","conversation_id","seq","author","author_id","author_name","author_avatar_url","body","client_id","created_at","edited_at"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}],"x-scope":"conversations:read"},"post":{"summary":"Send a reply or an internal note (idempotent on client_id). A reply turns the AI off.","tags":["Messages"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"cv","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/Message","$defs":{"Message":{"type":"object","properties":{"id":{"type":"string"},"conversation_id":{"type":"string"},"seq":{"type":"number"},"author":{"type":"string","enum":["visitor","agent","ai","system","note"]},"author_id":{"type":["string","null"]},"author_name":{"type":["string","null"]},"author_avatar_url":{"type":["string","null"]},"body":{"type":"string"},"meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"client_id":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"edited_at":{"type":["string","null"]}},"required":["id","conversation_id","seq","author","author_id","author_name","author_avatar_url","body","client_id","created_at","edited_at"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":4000},"client_id":{"type":"string","minLength":8,"maxLength":100},"note":{"type":"boolean"}},"required":["body"]}}}},"security":[{"bearer":[]}],"x-scope":"conversations:write"}},"/v1/workspaces/{ws}/conversations/{cv}/read":{"post":{"summary":"Mark read up to a seq (for me)","tags":["Conversations"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"cv","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"seq":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["seq"]}}}},"security":[{"bearer":[]}],"x-scope":"conversations:read"}},"/v1/workspaces/{ws}/conversations/{cv}/typing":{"post":{"summary":"Tell the visitor you are typing","tags":["Conversations"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"cv","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"typing":{"type":"boolean"}},"required":["typing"]}}}},"security":[{"bearer":[]}],"x-scope":"conversations:write"}},"/v1/workspaces/{ws}/conversations/{cv}/suggest":{"post":{"summary":"AI draft of the next reply","tags":["AI"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"cv","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"draft":{"type":"string"}},"required":["draft"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}],"x-scope":"conversations:read"}},"/v1/workspaces/{ws}/conversations/{cv}/summary":{"post":{"summary":"AI two-line summary","tags":["AI"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"cv","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}],"x-scope":"conversations:read"}},"/v1/workspaces/{ws}/visitors/{vis}":{"get":{"summary":"A visitor and their conversations","tags":["Visitors"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"vis","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}],"x-scope":"conversations:read"},"patch":{"summary":"Edit a visitor name or email","tags":["Visitors"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"vis","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"email":{"anyOf":[{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]}}}}}},"security":[{"bearer":[]}],"x-scope":"conversations:write"}},"/v1/workspaces/{ws}/saved-replies":{"get":{"summary":"List saved replies","tags":["Saved replies"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/$defs/SavedReply"},"$defs":{"SavedReply":{"type":"object","properties":{"id":{"type":"string"},"shortcut":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"}},"required":["id","shortcut","title","body"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}],"x-scope":"conversations:read"},"post":{"summary":"Create a saved reply","tags":["Saved replies"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/SavedReply","$defs":{"SavedReply":{"type":"object","properties":{"id":{"type":"string"},"shortcut":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"}},"required":["id","shortcut","title","body"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shortcut":{"type":"string","minLength":1,"maxLength":30,"pattern":"^[a-z0-9_-]+$"},"title":{"type":"string","minLength":1,"maxLength":80},"body":{"type":"string","minLength":1,"maxLength":4000}},"required":["shortcut","title","body"]}}}},"security":[{"bearer":[]}],"x-scope":"conversations:write"}},"/v1/workspaces/{ws}/saved-replies/{id}":{"patch":{"summary":"Edit a saved reply","tags":["Saved replies"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/SavedReply","$defs":{"SavedReply":{"type":"object","properties":{"id":{"type":"string"},"shortcut":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"}},"required":["id","shortcut","title","body"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shortcut":{"type":"string","minLength":1,"maxLength":30,"pattern":"^[a-z0-9_-]+$"},"title":{"type":"string","minLength":1,"maxLength":80},"body":{"type":"string","minLength":1,"maxLength":4000}}}}}},"security":[{"bearer":[]}],"x-scope":"conversations:write"},"delete":{"summary":"Delete a saved reply","tags":["Saved replies"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}],"x-scope":"conversations:write"}},"/v1/workspaces/{ws}/events":{"get":{"summary":"Events since a seq (7-day window; 410 gone when older)","tags":["Realtime"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"since","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}],"x-scope":"conversations:read"}},"/v1/workspaces/{ws}/socket":{"get":{"summary":"WebSocket upgrade (token and since in the query)","tags":["Realtime"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]}},"/v1/workspaces/{ws}/api-keys":{"get":{"summary":"List API keys","tags":["Developers"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/$defs/ApiKey"},"$defs":{"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["conversations:read","conversations:write","sites:read","sites:write","knowledge:write"]}},"last_used_at":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"secret":{"type":"string"}},"required":["id","name","prefix","scopes","last_used_at","created_at"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]},"post":{"summary":"Create an API key (secret shown once)","tags":["Developers"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/ApiKey","$defs":{"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["conversations:read","conversations:write","sites:read","sites:write","knowledge:write"]}},"last_used_at":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"secret":{"type":"string"}},"required":["id","name","prefix","scopes","last_used_at","created_at"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"scopes":{"minItems":1,"type":"array","items":{"type":"string","enum":["conversations:read","conversations:write","sites:read","sites:write","knowledge:write"]}}},"required":["name","scopes"]}}}},"security":[{"bearer":[]}]}},"/v1/workspaces/{ws}/api-keys/{id}":{"delete":{"summary":"Revoke an API key","tags":["Developers"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]}},"/v1/workspaces/{ws}/webhooks":{"get":{"summary":"List webhooks","tags":["Developers"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/$defs/Webhook"},"$defs":{"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"last_status":{"type":["number","null"]},"secret":{"type":"string"}},"required":["id","url","events","active","last_status"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]},"post":{"summary":"Create a webhook (Standard Webhooks signing; secret shown once)","tags":["Developers"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/Webhook","$defs":{"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"last_status":{"type":["number","null"]},"secret":{"type":"string"}},"required":["id","url","events","active","last_status"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":500,"format":"uri"},"events":{"default":[],"type":"array","items":{"type":"string"}}},"required":["url"]}}}},"security":[{"bearer":[]}]}},"/v1/workspaces/{ws}/webhooks/{id}":{"patch":{"summary":"Edit a webhook (re-activating resets the failure count)","tags":["Developers"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/$defs/Webhook","$defs":{"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"last_status":{"type":["number","null"]},"secret":{"type":"string"}},"required":["id","url","events","active","last_status"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":500,"format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"}}}}}},"security":[{"bearer":[]}]},"delete":{"summary":"Delete a webhook","tags":["Developers"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]}},"/v1/workspaces/{ws}/webhooks/{id}/test":{"post":{"summary":"Send a ping","tags":["Developers"],"parameters":[{"name":"ws","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":"number"}},"required":["ok","status"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]}},"/v1/widget/config":{"get":{"summary":"Public site appearance and availability","tags":["Widget"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"object","properties":{"name":{"type":"string"},"appearance":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"collect_email":{"type":"string"},"ai_enabled":{"type":"boolean"}},"required":["name","appearance","collect_email","ai_enabled"]},"online":{"type":"boolean"},"team":{"type":"array","items":{"type":"object","properties":{"name":{"type":["string","null"]},"avatar_url":{"type":["string","null"]}},"required":["name","avatar_url"]}},"reply_time":{"type":"string","enum":["few_minutes","hour","day"]},"offline_message":{"type":"string"}},"required":["site","online","team","reply_time","offline_message"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/widget/session":{"post":{"summary":"Start or resume a visitor session","tags":["Widget"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"string","minLength":1,"maxLength":100},"visitor_token":{"type":"string","maxLength":200},"page":{"type":"object","properties":{"url":{"type":"string","maxLength":2000},"title":{"type":"string","maxLength":300},"referrer":{"type":"string","maxLength":2000}}},"tz":{"type":"string","maxLength":60},"locale":{"type":"string","maxLength":20}},"required":["site"]}}}}}},"/v1/widget/messages":{"post":{"summary":"Send a visitor message (creates the conversation on the first one; idempotent on client_id)","tags":["Widget"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"conversation":{"$ref":"#/$defs/WidgetConversation"},"message":{"$ref":"#/$defs/WidgetMessage"}},"required":["conversation","message"],"$defs":{"WidgetConversation":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["open","closed"]},"ai_active":{"type":"boolean"},"assigned_name":{"type":["string","null"]}},"required":["id","status","ai_active","assigned_name"]},"WidgetMessage":{"type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"author":{"type":"string","enum":["visitor","agent","ai","system"]},"author_name":{"type":["string","null"]},"author_avatar_url":{"type":["string","null"]},"body":{"type":"string"},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"client_id":{"type":["string","null"]}},"required":["id","seq","author","author_name","author_avatar_url","body","created_at","client_id"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":4000},"client_id":{"type":"string","minLength":8,"maxLength":100},"page":{"type":"object","properties":{"url":{"type":"string","maxLength":2000},"title":{"type":"string","maxLength":300},"referrer":{"type":"string","maxLength":2000}}}},"required":["body","client_id"]}}}},"security":[{"visitorToken":[]}]},"get":{"summary":"Poll fallback: messages after a seq","tags":["Widget"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/$defs/WidgetMessage"}},"conversation":{"anyOf":[{"$ref":"#/$defs/WidgetConversation"},{"type":"null"}]},"agent_typing":{"type":"boolean"}},"required":["items","conversation","agent_typing"],"$defs":{"WidgetMessage":{"type":"object","properties":{"id":{"type":"string"},"seq":{"type":"number"},"author":{"type":"string","enum":["visitor","agent","ai","system"]},"author_name":{"type":["string","null"]},"author_avatar_url":{"type":["string","null"]},"body":{"type":"string"},"created_at":{"type":"string","description":"ISO-8601 UTC timestamp"},"client_id":{"type":["string","null"]}},"required":["id","seq","author","author_name","author_avatar_url","body","created_at","client_id"]},"WidgetConversation":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["open","closed"]},"ai_active":{"type":"boolean"},"assigned_name":{"type":["string","null"]}},"required":["id","status","ai_active","assigned_name"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"visitorToken":[]}]}},"/v1/widget/typing":{"post":{"summary":"Visitor typing indicator","tags":["Widget"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"typing":{"type":"boolean"},"preview":{"type":"string","maxLength":200}},"required":["typing"]}}}},"security":[{"visitorToken":[]}]}},"/v1/widget/identify":{"post":{"summary":"Attach name, email and custom attributes to the visitor","tags":["Widget"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"custom":{"type":"object","propertyNames":{"type":"string","maxLength":60},"additionalProperties":{"anyOf":[{"type":"string","maxLength":300},{"type":"number"},{"type":"boolean"}]}}}}}}},"security":[{"visitorToken":[]}]}},"/v1/widget/handoff":{"post":{"summary":"Ask for a person (AI stops, team is notified)","tags":["Widget"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"visitorToken":[]}]}},"/v1/widget/rating":{"post":{"summary":"Rate the conversation 1-5","tags":["Widget"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rating":{"type":"integer","minimum":1,"maximum":5}},"required":["rating"]}}}},"security":[{"visitorToken":[]}]}},"/v1/widget/conversation":{"delete":{"summary":"The visitor deletes their conversation","tags":["Widget"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"visitorToken":[]}]}},"/v1/widget/socket":{"get":{"summary":"Visitor WebSocket (site and visitor_token in the query)","tags":["Widget"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An `ak_…` session token (apps) or a `zxc_live_…` API key (integrations)."},"visitorToken":{"type":"apiKey","in":"header","name":"X-Visitor-Token"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["code","message"]}},"required":["error"]}}}}