{
  "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": "https://api-uat.famysync.com/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"
                }
              }
            }
          }
        }
      }
    }
  }
}
