{"openapi":"3.1.0","info":{"title":"Ambipath public conversations","version":"1.0.0","description":"Public questions, optional contact sharing and resumable operations. A conversation bearer authorizes only its own conversation. Customer-account permission and PAP request proofs are separate."},"servers":[{"url":"https://console.ambipath.com"}],"paths":{"/api/v1/public/{deploymentId}":{"get":{"summary":"Read enabled capabilities and HoverChat settings","parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Published assistant metadata","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Assistant is not published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/public/{deploymentId}/agent.md":{"get":{"summary":"Read browser-free public connection instructions","parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Public connection instructions","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Assistant is not published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/public/{deploymentId}/setup/SKILL.md":{"get":{"summary":"Download the website installation skill","parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Agent Skills installation instructions containing public coordinates only","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Assistant is not published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/public/{deploymentId}/setup/guide.md":{"get":{"summary":"Read the human installation guide","parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Website installation guide","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Assistant is not published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/public/{deploymentId}/session":{"post":{"summary":"Create or recover a guest conversation","parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionRequest"}}}},"description":"Create an operation ID and a random recovery secret before sending. Repeating both with the same channel returns the same session until it expires. Possession of the operation ID alone does not reveal the bearer. Keep both secrets private. An unused session does not appear as a chat.","responses":{"200":{"description":"Conversation session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The conversation session expired or was revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"This session does not own the conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision or operation conflict; read before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, capacity, or inference allowance limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds before retrying a rate-limited request"}}}}}},"/api/v1/public/{deploymentId}/conversations/{conversationId}":{"get":{"summary":"Read conversation and optional customer context","parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"security":[{"ConversationSession":[]}],"responses":{"200":{"description":"The latest 200 messages and events, requests, and authorized customer projection","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The conversation session expired or was revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"This session does not own the conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision or operation conflict; read before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, capacity, or inference allowance limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds before retrying a rate-limited request"}}}}}},"/api/v1/public/{deploymentId}/conversations/{conversationId}/events":{"get":{"summary":"Read a bounded page of events","security":[{"ConversationSession":[]}],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"after","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}],"responses":{"200":{"description":"Ordered events with nextCursor and hasMore","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The conversation session expired or was revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"This session does not own the conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision or operation conflict; read before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, capacity, or inference allowance limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds before retrying a rate-limited request"}}}}}},"/api/v1/public/{deploymentId}/conversations/{conversationId}/messages":{"post":{"summary":"Submit one question","security":[{"ConversationSession":[]}],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"responses":{"200":{"description":"Acknowledged message and queued conversation","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The conversation session expired or was revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"This session does not own the conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision or operation conflict; read before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, capacity, or inference allowance limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds before retrying a rate-limited request"}}}}}},"/api/v1/public/{deploymentId}/conversations/{conversationId}/context":{"post":{"summary":"Edit context for the next question","security":[{"ConversationSession":[]}],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Context"}}}},"responses":{"200":{"description":"Current customer projection; no inference is triggered","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The conversation session expired or was revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"This session does not own the conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision or operation conflict; read before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, capacity, or inference allowance limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds before retrying a rate-limited request"}}}}}},"/api/v1/public/{deploymentId}/conversations/{conversationId}/contact":{"post":{"summary":"Share, edit, or clear optional contact details","security":[{"ConversationSession":[]}],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"responses":{"200":{"description":"Current customer projection; contact fields are not model input","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The conversation session expired or was revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"This session does not own the conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision or operation conflict; read before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, capacity, or inference allowance limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds before retrying a rate-limited request"}}}}}},"/api/v1/public/{deploymentId}/conversations/{conversationId}/follow-up/{requestId}":{"post":{"summary":"Withdraw your follow-up request","security":[{"ConversationSession":[]}],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowUp"}}}},"responses":{"200":{"description":"Current customer projection","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The conversation session expired or was revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"This session does not own the conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision or operation conflict; read before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, capacity, or inference allowance limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds before retrying a rate-limited request"}}}},"description":"Public sessions can only withdraw. Contacted and completed are staff actions."}},"/api/v1/public/{deploymentId}/conversations/{conversationId}/close":{"post":{"summary":"Close a conversation","security":[{"ConversationSession":[]}],"parameters":[{"name":"deploymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Command"}}}},"responses":{"200":{"description":"Closed conversation; history is retained","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The conversation session expired or was revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"This session does not own the conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision or operation conflict; read before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, capacity, or inference allowance limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds before retrying a rate-limited request"}}}}}},"/api/operations/{operationId}":{"get":{"summary":"Reconcile an uncertain acknowledgement","security":[{"ConversationSession":[]}],"parameters":[{"name":"operationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"description":"Read before retrying a question. A 404 means no acknowledgement was recorded. Retry the original body and operation ID; never post a second question to poll.","responses":{"200":{"description":"Recorded operation status/result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The conversation session expired or was revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"This session does not own the conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No recorded acknowledgement","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision or operation conflict; read before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, capacity, or inference allowance limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds before retrying a rate-limited request"}}}}}}},"components":{"securitySchemes":{"ConversationSession":{"type":"http","scheme":"bearer"}},"schemas":{"SessionRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"recoverySecret":{"type":"string","minLength":32,"maxLength":200,"pattern":"^[A-Za-z0-9_-]+$"},"channel":{"default":"headless","type":"string","enum":["website","headless","guest_mcp"]}},"required":["operationId","recoverySecret","channel"],"additionalProperties":false},"Message":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"reason_for_question":{"type":"object","properties":{"value":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"basis":{"type":"string","enum":["customer_entry","reported_by_caller","unknown","withheld","cleared"]}},"required":["value","basis"],"additionalProperties":false},"requirements":{"type":"object","properties":{"status":{"type":"string","enum":["provided","unknown","withheld","cleared"]},"items":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"value":{"type":"string","maxLength":2000},"basis":{"type":"string","enum":["customer_entry","reported_by_caller"]}},"required":["name","value","basis"],"additionalProperties":false}}},"required":["status","items"],"additionalProperties":false},"text":{"type":"string","minLength":1,"maxLength":8000},"messageId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"hostContext":{},"contextRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["operationId","expectedRevision","text"],"additionalProperties":false},"Context":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"reason_for_question":{"type":"object","properties":{"value":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"basis":{"type":"string","enum":["customer_entry","reported_by_caller","unknown","withheld","cleared"]}},"required":["value","basis"],"additionalProperties":false},"requirements":{"type":"object","properties":{"status":{"type":"string","enum":["provided","unknown","withheld","cleared"]},"items":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"value":{"type":"string","maxLength":2000},"basis":{"type":"string","enum":["customer_entry","reported_by_caller"]}},"required":["name","value","basis"],"additionalProperties":false}}},"required":["status","items"],"additionalProperties":false}},"required":["operationId","expectedRevision"],"additionalProperties":false},"Contact":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"name":{"anyOf":[{"type":"string","maxLength":150},{"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"}]},"followUp":{"type":"boolean"}},"required":["operationId","expectedRevision"],"additionalProperties":false},"FollowUp":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["contacted","completed","withdrawn"]}},"required":["operationId","expectedRevision","status"],"additionalProperties":false},"Command":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"operationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["operationId","expectedRevision"],"additionalProperties":false},"Session":{"type":"object","required":["token","conversationId","visitorId","revision","expiresAt","apiVersion"],"properties":{"token":{"type":"string","writeOnly":true},"conversationId":{"type":"string","format":"uuid"},"visitorId":{"type":"string","format":"uuid"},"revision":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"tenantName":{"type":"string"},"apiVersion":{"const":"1"}}},"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"currentRevision":{"type":"integer"}}}}}}}}