{"openapi":"3.1.0","info":{"title":"Famysync API","version":"1.1.0","description":"Public REST API for Famysync — AI support agents with chat + voice in the languages Asia speaks. Authenticate with a scoped API token (create one in Dashboard → API & Agents): `Authorization: Bearer mgpt_…`. Requests require live API access on an active Growth trial, eligible paid Growth/Scale plan, or API-enabled enterprise contract. This workspace API is separate from Enterprise Vendor API. Secret tokens must stay on your server: browsers cannot call the token endpoints (no CORS). To call a bot from your own web page, use its public key with POST /public/chat."},"servers":[{"url":"/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API token from Dashboard → API (mgpt_…)"},"publicKey":{"type":"apiKey","in":"header","name":"X-Famysync-Key","description":"Public chat key from Dashboard → API (mpk_…). Safe in a web page; works only from the bot’s allowed domains."}},"schemas":{"CreatedBot":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"language":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","name","language","created_at"]},"Conversation":{"type":"object","properties":{"session_id":{"type":"string"},"message_count":{"type":"integer"},"first_at":{"type":"string","format":"date-time"},"last_at":{"type":"string","format":"date-time"},"preview":{"type":["string","null"]},"channel":{"type":"string"}}},"ChatMessage":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"chatbot_id":{"type":["string","null"],"format":"uuid"},"session_id":{"type":"string"},"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"},"feedback":{"type":["string","null"],"enum":["positive","negative",null]},"source_urls":{"type":["array","null"],"items":{"type":"string"}},"channel":{"type":"string"},"provider_message_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"Lead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"chatbot_id":{"type":["string","null"],"format":"uuid"},"session_id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"external_user_id":{"type":["string","null"]},"company":{"type":["string","null"]},"intent_category":{"type":["string","null"]},"intent_summary":{"type":["string","null"]},"score":{"type":"integer"},"score_band":{"type":"string","enum":["hot","warm","cold"]},"sentiment":{"type":["string","null"]},"qualification":{"type":["object","null"],"additionalProperties":{"type":"string"}},"status":{"type":"string","enum":["new","contacted","qualified","won","lost"]},"captured_via":{"type":"string","enum":["conversational","form","inferred"]},"confidence":{"type":["number","null"]},"notified_at":{"type":["string","null"],"format":"date-time"},"asked_contact_at":{"type":["string","null"],"format":"date-time"},"notes":{"type":["string","null"]},"country":{"type":["string","null"]},"region":{"type":["string","null"]},"channel":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Analytics":{"type":"object","properties":{"daily":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string","format":"date"},"user_messages":{"type":"integer"},"assistant_messages":{"type":"integer"}}}},"top_questions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"times":{"type":"integer"}}}},"unanswered":{"type":"object","properties":{"count":{"type":"integer"},"total":{"type":"integer"},"rate":{"type":"number","description":"Percentage from 0 to 100, rounded to one decimal place."}}},"feedback":{"type":"object","properties":{"positive":{"type":"integer"},"negative":{"type":"integer"}}},"sessions":{"type":"object","properties":{"total":{"type":"integer"},"avg_messages":{"type":"number"}}}},"required":["daily","top_questions","unanswered","feedback","sessions"]},"Booking":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"chatbot_id":{"type":["string","null"],"format":"uuid"},"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"notes":{"type":["string","null"]},"requested_slot":{"type":["string","null"],"format":"date-time"},"country":{"type":["string","null"]},"time_zone":{"type":["string","null"]},"custom_fields":{"type":["object","null"],"additionalProperties":{"type":"string"}},"status":{"type":"string","enum":["pending","confirmed","rejected","cancelled"]},"rejection_comment":{"type":["string","null"]},"cancel_comment":{"type":["string","null"],"description":"Why the business cancelled (sent to the visitor)."},"confirmed_at":{"type":["string","null"],"format":"date-time"},"rejected_at":{"type":["string","null"],"format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"ChatReply":{"type":"object","properties":{"sessionId":{"type":"string","description":"Pass it back to continue the conversation."},"answer":{"type":"string","description":"The reply text, without suggestion line or hidden markers."},"sources":{"type":"array","items":{"type":"string","format":"uri"},"description":"Pages the reply is based on: links the reply gives first, then the knowledge pages closest to the question."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested follow-up questions."},"handoff":{"type":"boolean","description":"The bot offered human support."},"askContact":{"type":"boolean","description":"The bot asked for contact details."},"offerBooking":{"type":"boolean","description":"The bot offered a booking."}},"required":["sessionId","answer","sources","suggestions","handoff","askContact","offerBooking"]},"ChatDone":{"type":"object","properties":{"sessionId":{"type":"string"},"sources":{"type":"array","items":{"type":"string","format":"uri"}},"suggestions":{"type":"array","items":{"type":"string"}},"handoff":{"type":"boolean"},"askContact":{"type":"boolean"},"offerBooking":{"type":"boolean"}}},"BotSettings":{"type":"object","properties":{"chatbotId":{"type":"string","format":"uuid"},"language":{"type":"string"},"languageMode":{"type":"string","enum":["match","fixed"]},"supportedLanguages":{"type":"array","items":{"type":"string"}},"instructions":{"type":"string","description":"The instructions the bot follows now (a preset’s text when a preset is chosen)."},"instructionPreset":{"type":"string"},"persona":{"type":"string"},"personaPreset":{"type":"string"},"fallbackMessage":{"type":"string"}}},"CustomAnswer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"question":{"type":"string"},"answer":{"type":"string"},"status":{"type":"string","enum":["queued","processing","ready","failed"]},"chatbot_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"synced_at":{"type":["string","null"],"format":"date-time"}}},"ValidationError":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":true,"description":"Structured validation error; inspect its issues."}}},"Bot":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":30},"slot_kind":{"type":"string","enum":["plan","addon","vendor"]},"language":{"type":"string","example":"ja-JP","description":"Default reply language (as in the dashboard)."},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"KBDocument":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"source_url":{"type":["string","null"]},"source_type":{"type":"string","enum":["url","file","qa","snippet"]},"status":{"type":"string","enum":["queued","processing","ready","failed"]},"chunk_count":{"type":"integer"},"chatbot_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"synced_at":{"type":["string","null"],"format":"date-time","description":"Last successful training."},"last_attempt_at":{"type":["string","null"],"format":"date-time","description":"Last time it was sent to training."},"error_code":{"type":["string","null"],"example":"embed_too_large"},"error":{"type":["string","null"],"description":"Why the last training failed."}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"retry_after":{"type":"integer"},"suggested_name":{"type":"string"},"available_slots":{"type":"object","additionalProperties":{"type":"integer"}}}}}},"paths":{"/bots":{"get":{"summary":"List bots","description":"Requires scope `bots:read`.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Bot list. A token covers one workspace (`workspace`).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Bot"}},"workspace":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]}}}}}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}},"post":{"summary":"Create a bot","description":"Requires scope `bots:write`. `language` becomes the bot’s default reply language. Bot-restricted tokens cannot create bots. Enterprise workspaces must supply `enterprise_plan_tier` and have an available slot in that tier.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":30},"language":{"type":"string","example":"en-US"},"enterprise_plan_tier":{"type":"string","enum":["starter","growth","scale"],"description":"Required for enterprise workspaces"}}}}}},"responses":{"201":{"description":"Created bot","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Bot"}},"required":["data"]}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Bot name is already used; inspect suggested_name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/bots/{id}/settings":{"get":{"summary":"Get a bot’s instructions and language settings","description":"Requires scope `bots:read`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BotSettings"}},"required":["data"]}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/bots/{id}/instructions":{"patch":{"summary":"Replace instructions, persona and/or fallback message","description":"Requires scope `settings:write`. Pass only what changes; each field replaces the whole text and switches its preset to custom. The response has the new settings in `data` and the old ones in `previous`, to undo the change.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"instructions":{"type":"string","maxLength":4000},"persona":{"type":"string","maxLength":2000},"fallbackMessage":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BotSettings"},"previous":{"$ref":"#/components/schemas/BotSettings"}}}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/kb":{"get":{"summary":"List knowledge-base documents","description":"Requires scope `kb:read`. Newest first. Without `limit` every document is returned; with it, page with `offset` (`total` says how many match).","security":[{"bearerAuth":[]}],"parameters":[{"name":"chatbotId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","schema":{"type":"string","enum":["queued","processing","ready","failed"]}},{"name":"type","in":"query","schema":{"type":"string","enum":["url","file","qa","snippet"]}},{"name":"q","in":"query","description":"Part of the title or address","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Document list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KBDocument"}},"total":{"type":"integer"},"limit":{"type":["integer","null"]},"offset":{"type":"integer"}}}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/kb/{id}":{"delete":{"summary":"Delete a knowledge-base document","description":"Requires scope `kb:write`. Any kind (page, file, snippet, custom answer). The bot stops using it straight away; cannot be undone.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"string","format":"uuid"}}}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/custom-answers":{"get":{"summary":"List custom answers","description":"Requires scope `kb:read`. Custom answers take priority over other knowledge.","security":[{"bearerAuth":[]}],"parameters":[{"name":"chatbotId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Custom answers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomAnswer"}}},"required":["data"]}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}},"post":{"summary":"Add a custom answer","description":"Requires scope `kb:write`. Used once trained (about 2 minutes).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chatbotId","question","answer"],"properties":{"chatbotId":{"type":"string","format":"uuid"},"question":{"type":"string","maxLength":500},"answer":{"type":"string","maxLength":5000}}}}}},"responses":{"202":{"description":"Queued for training","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomAnswer"}},"required":["data"]}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/custom-answers/{id}":{"patch":{"summary":"Change a custom answer","description":"Requires scope `kb:write`. The old answer is used until the new one is trained. `previous` has the old text.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"question":{"type":"string","maxLength":500},"answer":{"type":"string","maxLength":5000}}}}}},"responses":{"202":{"description":"Queued for training","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomAnswer"},"previous":{"$ref":"#/components/schemas/CustomAnswer"}}}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}},"delete":{"summary":"Delete a custom answer","description":"Requires scope `kb:write`. Cannot be undone.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"string","format":"uuid"}}}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/kb/ingest":{"post":{"summary":"Add knowledge (URL or raw text)","description":"Requires scope `kb:write`. Queued for crawling/embedding; poll GET /kb for status.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"anyOf":[{"required":["url"]},{"required":["text"],"properties":{"text":{"minLength":1}}}],"properties":{"title":{"type":"string","minLength":1,"maxLength":300},"url":{"type":"string","format":"uri"},"text":{"type":"string","maxLength":200000},"chatbotId":{"type":"string","format":"uuid"}}}}}},"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}}}}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/chat":{"post":{"summary":"Chat with a bot","description":"Requires scope `chat:invoke`. Every message is saved as a conversation (channel `api`) and counts toward your monthly message quota; without `sessionId` a new conversation is started and its id returned (`X-Session-Id` header and the `done` event). By default the reply is a Server-Sent Events stream: text pieces as OpenAI-style chunks (`data: {\"choices\":[{\"delta\":{\"content\":\"…\"}}]}`), then `event: done` with the sources, suggested questions and actions (ChatDone), then `data: [DONE]`. With `\"stream\": false` the whole reply comes back as one JSON object (ChatReply).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","minLength":1,"maxLength":2000},"chatbotId":{"type":"string","format":"uuid"},"sessionId":{"type":"string","maxLength":120,"description":"Stable id groups turns into one conversation"},"language":{"type":"string","example":"ja-JP","description":"Reply language. Any supported code, e.g. en-US, es-US, fr-FR, pt-BR, ht-HT, ru-RU, de-DE, it-IT, pl-PL, fa-IR, en-IN, ja-JP, ko-KR, zh-CN, ms-MY, id-ID, th-TH, vi-VN, fil-PH, ar-AE, hi-IN, ta-IN, sw-KE, ha-NG, yo-NG. Omit to use the bot’s default; the bot still matches the language the user writes in."},"stream":{"type":"boolean","default":true,"description":"false: one JSON reply instead of a stream."}}}}}},"responses":{"200":{"description":"SSE stream, or JSON with \"stream\": false","headers":{"X-Session-Id":{"description":"The conversation id.","schema":{"type":"string"}}},"content":{"text/event-stream":{"schema":{"type":"string","description":"Text chunks, then `event: done` (ChatDone JSON), then `data: [DONE]`."},"example":"data: {\"choices\":[{\"delta\":{\"content\":\"Hello\"}}]}\n\nevent: done\ndata: {\"sessionId\":\"api-…\",\"sources\":[\"https://example.com/faq\"],\"suggestions\":[\"How do I book?\"],\"handoff\":false,\"askContact\":false,\"offerBooking\":false}\n\ndata: [DONE]\n\n"},"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatReply"}}}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/public/chat":{"post":{"summary":"Chat from your own web page (public key)","description":"For a browser: send the bot’s public key (`X-Famysync-Key: mpk_…`, from Dashboard → API). It can only chat with that one bot, and only from the bot’s allowed domains, which must be switched on. Same request and reply as POST /chat (without `chatbotId`). Rate limited per key and per visitor. Never put a secret token (mgpt_…) in a web page; it is refused here.","security":[{"publicKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","minLength":1,"maxLength":2000},"sessionId":{"type":"string","maxLength":120},"language":{"type":"string","example":"ja-JP"},"stream":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Same as POST /chat","content":{"text/event-stream":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatReply"}}}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Allowed domains are off for this bot (`domains_required`) or the page is not on them (`origin_not_allowed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/conversations":{"get":{"summary":"List conversations","description":"Requires scope `conversations:read`. Supports `?q=` search, `?limit=`, `?chatbotId=`, `?channel=` (web, api, mcp, email, whatsapp). Default limit 50, maximum 200; no page or cursor parameter.","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":200}},{"name":"channel","in":"query","schema":{"type":"string","enum":["web","api","mcp","email","whatsapp"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"chatbotId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Session list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}}},"required":["data"]}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/conversations/{sessionId}":{"get":{"summary":"Get a conversation transcript","description":"Requires scope `conversations:read`. Returns an array; a missing session can return an empty array. Restricted tokens may receive 403 for inaccessible sessions.","security":[{"bearerAuth":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Messages in the session","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}}},"required":["data"]}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/leads":{"get":{"summary":"List leads","description":"Requires scope `leads:read`. At most 500 intent-scored leads, newest first; no cursor pagination; optional `?chatbotId=`. Each lead has score/band, an AI summary, contact details, qualification, and `external_user_id` when the visitor was signed in (Famysync.identify).","security":[{"bearerAuth":[]}],"parameters":[{"name":"chatbotId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Lead list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}}},"required":["data"]}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/analytics":{"get":{"summary":"Analytics summary (30 days)","description":"Requires scope `analytics:read`. Daily volumes, top questions, unanswered rate, feedback, sessions.","security":[{"bearerAuth":[]}],"parameters":[{"name":"chatbotId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Analytics summary","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Analytics"}},"required":["data"]}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/bookings":{"get":{"summary":"List bookings","description":"Requires scope `bookings:read`. Appointment requests newest first. Filter with `?status=pending|confirmed|rejected|cancelled`, `?chatbotId=`, `?limit=`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","confirmed","rejected","cancelled"]}},{"name":"chatbotId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":200}}],"responses":{"200":{"description":"Booking list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Booking"}}},"required":["data"]}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/bookings/{id}":{"get":{"summary":"Get a booking","description":"Requires scope `bookings:read`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Booking","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Booking"}},"required":["data"]}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}},"patch":{"summary":"Update a booking","description":"Requires scope `bookings:write`. `action` is `confirm`, `reject`, `reschedule`, or `cancel`. Confirm/reject apply to pending requests. Reschedule and cancel apply to pending or confirmed bookings and email the visitor. Reschedule requires `requestedSlot`. Optional `cancelComment` (saved as `cancel_comment`) / `rejectionComment` (saved as `rejection_comment`) is included in the visitor email.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"allOf":[{"if":{"properties":{"action":{"const":"reschedule"}}},"then":{"required":["requestedSlot"]}}],"properties":{"action":{"type":"string","enum":["confirm","reject","reschedule","cancel"]},"requestedSlot":{"type":"string","format":"date-time"},"rejectionComment":{"type":"string","maxLength":500},"cancelComment":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Updated booking","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Booking"}},"required":["data"]}}}},"400":{"description":"Invalid input or operation requirements. Validation can return a structured error.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/ValidationError"}]}}}},"401":{"description":"Missing, invalid, expired or revoked API token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"API/live service unavailable (api_locked), plan capacity or quota exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required scope or bot access is missing, or enterprise tier capacity is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Record or account not found in the accessible context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Slot taken, already decided or booking no longer active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Wait before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}}}}