{ "openapi": "3.1.0", "info": { "title": "RAG Backend API", "version": "1.0.0" }, "paths": { "/auth/me/entitlements": { "get": { "tags": [ "auth" ], "summary": "Get My Entitlements", "description": "Return the resolved plan entitlements for the authenticated workspace.\n\nUsed by the admin app's ``useEntitlements`` hook to drive every feature\ngate, limit display, and upgrade prompt without each component\nre-fetching the plan. Operators see the entitlements of the client\nthey belong to \u2014 that's the workspace they're acting in, not their\nown (operators don't have personal subscriptions).\n\nResponse shape mirrors ``PlanEntitlements.to_json_dict()`` plus a small\nset of derived booleans the UI uses heavily.", "operationId": "get_my_entitlements_auth_me_entitlements_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/auth/me": { "get": { "tags": [ "auth" ], "summary": "Get Current User Endpoint", "description": "Return the authenticated principal's profile + workspace bot count.\n\nUsed by the admin TopBar to populate the user-menu dropdown (email,\njoining date, bots). Accepts BOTH ``X-API-Key`` (clients) and\n``X-Operator-Key`` (operators) so the dropdown works regardless of how\nthe user logged in. For an operator, ``bot_count`` is the count of bots\nin their workspace (the client they belong to) \u2014 that's what the user\nexpects to see for the \"X bots\" line, not zero.", "operationId": "get_current_user_endpoint_auth_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentUserResponse" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/auth/verify-email": { "post": { "tags": [ "auth" ], "summary": "Verify Email", "description": "Verify a client's email using the 6-digit OTP sent at registration.", "operationId": "verify_email_auth_verify_email_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/resend-verification": { "post": { "tags": [ "auth" ], "summary": "Resend Verification", "description": "Re-send a fresh 6-digit verification OTP. Safe to call on unknown emails.", "operationId": "resend_verification_auth_resend_verification_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendVerificationRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/login": { "post": { "tags": [ "auth" ], "summary": "Login", "description": "Authenticate a Client and return their permanent API key.", "operationId": "login_auth_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/register": { "post": { "tags": [ "auth" ], "summary": "Register", "description": "Self-service client registration.\nCreates a new client account and returns an API key for immediate login.", "operationId": "register_auth_register_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/request-password-reset": { "post": { "tags": [ "auth" ], "summary": "Request Password Reset", "description": "Generates an OTP and sends it via email.", "operationId": "request_password_reset_auth_request_password_reset_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestPasswordResetRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/reset-password": { "post": { "tags": [ "auth" ], "summary": "Reset Password", "description": "Verifies OTP and resets the password.", "operationId": "reset_password_auth_reset_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/operator-login": { "post": { "tags": [ "auth" ], "summary": "Operator Login", "description": "Authenticate an Operator via email and password.\nReturns the Operator's API Key for subsequent requests via X-Operator-Key header.", "operationId": "operator_login_auth_operator_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorLoginRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorLoginResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/operator-change-password": { "post": { "tags": [ "auth" ], "summary": "Operator Change Password", "description": "Operator changes their own password.", "operationId": "operator_change_password_auth_operator_change_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorChangePasswordRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/auth/google/login": { "get": { "tags": [ "oauth" ], "summary": "Google Login", "description": "Kick off the Google OAuth flow.\n\nIssues the state cookie and 302-redirects to Google's consent screen.\n``next`` is an optional relative path to land on after success (e.g.\n``/billing``). ``mode`` is telemetry only \u2014 backend behaviour is the\nsame for login and signup.", "operationId": "google_login_auth_google_login_get", "parameters": [ { "name": "next", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next" } }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "default": "login", "title": "Mode" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/google/callback": { "get": { "tags": [ "oauth" ], "summary": "Google Callback", "description": "Handle Google's redirect back into the app.\n\nValidates the CSRF state cookie, exchanges the code for a verified\nGoogle profile, then resolves the Client through three matching\nlayers (see ``_resolve_client_for_profile``) and issues a 302 to the\nfrontend with the api_key in the URL fragment.", "operationId": "google_callback_auth_google_callback_get", "parameters": [ { "name": "code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code" } }, { "name": "state", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" } }, { "name": "error", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/auth/google/status": { "get": { "tags": [ "oauth" ], "summary": "Google Oauth Status", "description": "Tell the frontend whether the Google button should render.\n\nReturning a single boolean keeps the frontend logic trivial \u2014 if the\nserver hasn't been configured with credentials, the button hides\nitself rather than 503-ing on click.", "operationId": "google_oauth_status_auth_google_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/superadmin/clients": { "get": { "tags": [ "superadmin" ], "summary": "List Clients", "description": "Superadmin only: Get all clients on the platform.", "operationId": "list_clients_superadmin_clients_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] }, "post": { "tags": [ "superadmin" ], "summary": "Create Client", "description": "Superadmin only: Create a new Client account.\nClient will create their own bots from the dashboard.", "operationId": "create_client_superadmin_clients_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/clients/{client_id}": { "delete": { "tags": [ "superadmin" ], "summary": "Delete Client", "description": "Superadmin only: Delete a client and ALL their data (bots, documents, sessions, messages).\nCannot delete yourself (the superadmin account).", "operationId": "delete_client_superadmin_clients__client_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Client Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "superadmin-v2" ], "summary": "Client Detail", "description": "Aggregated client detail used by ``/clients/[id]`` page.", "operationId": "client_detail_superadmin_clients__client_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Client Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "superadmin-v2" ], "summary": "Patch Client", "operationId": "patch_client_superadmin_clients__client_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Client Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientPatch" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/stats": { "get": { "tags": [ "superadmin" ], "summary": "Get Global Stats", "description": "Superadmin only: Get aggregate global usage stats (Total Clients, Total Messages).", "operationId": "get_global_stats_superadmin_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/feedback": { "get": { "tags": [ "superadmin" ], "summary": "Get Global Feedback", "description": "Superadmin only: Get all feedback across all clients.", "operationId": "get_global_feedback_superadmin_feedback_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/platform-feedback": { "get": { "tags": [ "superadmin" ], "summary": "Get Platform Feedback", "description": "Superadmin only: Get all customer-submitted platform feedback. Optionally\nfilter by resolution ``status`` and/or taxonomy (``type``/``area``/``severity``).", "operationId": "get_platform_feedback_superadmin_platform_feedback_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } }, { "name": "area", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Area" } }, { "name": "severity", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Severity" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/platform-feedback/{feedback_id}": { "patch": { "tags": [ "superadmin" ], "summary": "Update Platform Feedback", "description": "Superadmin only: triage/resolve a customer's platform feedback.\n\nUpdates ``status`` and/or ``admin_response``. Transitioning into a resolved\nstate (``resolved``/``closed``) stamps ``resolved_at``/``resolved_by`` and\nenqueues an in-app notification for the owning client. Audit-logged.", "operationId": "update_platform_feedback_superadmin_platform_feedback__feedback_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "feedback_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Feedback Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformFeedbackUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/demo/{bot_key}": { "get": { "tags": [ "bots" ], "summary": "Get Bot Demo Page", "description": "Render a shareable demo page, or an iframe-based preview when *url* is supplied.\n\nWhen ``edit=1`` is passed, the page enables a postMessage bridge so the\nembedding dashboard can drive widget appearance in real time.", "operationId": "get_bot_demo_page_demo__bot_key__get", "parameters": [ { "name": "bot_key", "in": "path", "required": true, "schema": { "type": "string", "title": "Bot Key" } }, { "name": "url", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" } }, { "name": "edit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1, "minimum": 0, "default": 0, "title": "Edit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "text/html": { "schema": { "type": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/bots/settings/public": { "get": { "tags": [ "bots" ], "summary": "Get Bot Settings Public", "description": "Public endpoint for the widget to fetch bot settings.\nAuthenticated via X-Bot-Key or X-API-Key (backward compat).\n\nIncludes the bot owner's subscription health so the widget can choose\nto suppress the launcher (or render an offline indicator) when the\nworkspace is not serving. ``is_offline=True`` means visitors who do\nopen the widget will only get the configured ``offline_message`` \u2014\nthe chat endpoint will not run RAG.", "operationId": "get_bot_settings_public_bots_settings_public_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/bots": { "get": { "tags": [ "bots" ], "summary": "List Bots", "description": "List all bots for the authenticated client or agent's client.", "operationId": "list_bots_bots_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/BotResponse" }, "type": "array", "title": "Response List Bots Bots Get" } } } } }, "security": [ { "APIKeyHeader": [] } ] }, "post": { "tags": [ "bots" ], "summary": "Create Bot", "description": "Create a new bot for the authenticated workspace.\n\nSubscription-gated: workspaces whose owner's trial has expired (or\nwhose subscription is otherwise inactive) get a 403 with\n``error: subscription_required``. The dashboard's read-only mode\nsurfaces a \"Reactivate to add a new bot\" banner instead of letting\nthe customer queue work they can't complete.", "operationId": "create_bot_bots_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBotRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/bots/checkout": { "post": { "tags": [ "bots" ], "summary": "Create Bot Checkout", "description": "Mint a Razorpay subscription for one new bot.\n\nReturns the Razorpay Checkout payload (``subscription_id``,\n``key_id``, prefill). The frontend opens Razorpay; on success it\ncalls ``POST /bots/checkout/verify`` (or the production webhook\narrives first) to materialise the new Bot row.\n\nFree / first-bot creation does NOT go through this endpoint \u2014 that\nkeeps using ``POST /bots`` directly. Use ``can_client_add_new_bot``\nto decide which path the frontend should take.", "operationId": "create_bot_checkout_bots_checkout_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BotCheckoutRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/bots/checkout/verify": { "post": { "tags": [ "bots" ], "summary": "Verify Bot Checkout", "description": "Verify the Razorpay success callback and materialise the new bot.\n\nWebhook delivery is the source of truth in production; this endpoint\nis the sync fallback so the customer doesn't have to wait for the\nwebhook to land before seeing their new bot. Idempotent: if the\nsubscription's activation webhook arrived first, the local row\nalready exists and the handler short-circuits.", "operationId": "verify_bot_checkout_bots_checkout_verify_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BotCheckoutVerifyRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/bots/{bot_id}/demo-share-click": { "post": { "tags": [ "bots" ], "summary": "Track Demo Share Click", "description": "Record that an authenticated workspace user copied a bot demo link.", "operationId": "track_demo_share_click_bots__bot_id__demo_share_click_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/bots/{bot_id}/framework-presets": { "get": { "tags": [ "bots" ], "summary": "Get Framework Presets", "operationId": "get_framework_presets_bots__bot_id__framework_presets_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/bots/{bot_id}": { "get": { "tags": [ "bots" ], "summary": "Get Bot", "description": "Get details of a specific bot owned by the authenticated workspace.", "operationId": "get_bot_bots__bot_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "bots" ], "summary": "Update Bot", "description": "Update settings for a specific bot.", "operationId": "update_bot_bots__bot_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Bot Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBotRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "bots" ], "summary": "Delete Bot", "description": "Delete a bot and all its data (documents, sessions, messages).\n\nWhen the bot has its own per-bot subscription, cancel that\nsubscription first (both with Razorpay and locally). Two reasons:\n\n1. **Stop the bill.** Leaving the subscription active after the bot\n is gone would keep charging the customer for nothing.\n2. **Side-step the partial unique index.** ``subscriptions.bot_id``\n is ``ON DELETE SET NULL``, so deleting the bot would otherwise\n null the FK on an ``active`` subscription \u2014 which collides with\n ``ix_subscriptions_client_legacy_active`` (only one client-level\n active sub per client). Marking the sub ``canceled`` first takes\n it out of that index's predicate before the row is touched.\n\nThe legacy / Free bot path (no ``subscription_id``) skips this and\njust deletes the bot as before.", "operationId": "delete_bot_bots__bot_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/bots/{bot_id}/recrawl": { "get": { "tags": [ "bots" ], "summary": "Get Recrawl Status", "description": "Return the current auto-recrawl state + last-run summary for a bot.", "operationId": "get_recrawl_status_bots__bot_id__recrawl_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecrawlStatusResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "bots" ], "summary": "Update Recrawl", "description": "Toggle auto-recrawl on or off for a bot.\n\nEnabling requires the ``auto_recrawl`` feature flag on the client's\nplan \u2014 Free / Starter plans get a structured 403 the admin UI catches\nand routes to the upgrade flow. Disabling always succeeds so a\ncustomer can turn the feature off even after a plan downgrade left\nthem without the entitlement.", "operationId": "update_recrawl_bots__bot_id__recrawl_patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Bot Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecrawlUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecrawlStatusResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/chat": { "post": { "tags": [ "chat" ], "summary": "Chat Endpoint", "description": "RAG Endpoint: Analyzes the question, retrieves relevant documents for the bot,\nand generates a standalone answer.\nAuthenticated via X-Bot-Key or X-API-Key (resolves default bot).", "operationId": "chat_endpoint_chat_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/chat/stream": { "post": { "tags": [ "chat" ], "summary": "Chat Stream Endpoint", "description": "Streaming RAG Endpoint: Streams the response token-by-token via SSE.\nProtocol: METADATA:{json} \u2192 text chunks \u2192 FINAL_METADATA:{json}\nAuthenticated via X-Bot-Key or X-API-Key (resolves default bot).", "operationId": "chat_stream_endpoint_chat_stream_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/chat/lead-capture": { "post": { "tags": [ "chat" ], "summary": "Lead Capture Endpoint", "description": "Capture lead contact info from pre-chat or handoff form. Auth: X-Bot-Key.", "operationId": "lead_capture_endpoint_chat_lead_capture_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadCaptureRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/chat/behavioral-signals": { "post": { "tags": [ "chat" ], "summary": "Behavioral Signals Endpoint", "description": "Receive behavioral signals from the widget and compute a behavioral score.\n\nCalled on session init with page context, and on beforeunload with time-on-page.\nAuth: X-Bot-Key.", "operationId": "behavioral_signals_endpoint_chat_behavioral_signals_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BehavioralSignalsRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/chat/meeting-booked": { "post": { "tags": [ "chat" ], "summary": "Meeting Booked Endpoint", "operationId": "meeting_booked_endpoint_chat_meeting_booked_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingBookedRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/chat/lead-info/{session_id}": { "get": { "tags": [ "chat" ], "summary": "Get Lead Info Endpoint", "description": "Fetch existing lead info for a widget session. Auth: X-Bot-Key.\nAlways returns HTTP 200 \u2014 non-critical endpoint that must never block widget load.\nUsed by the widget to pre-fill HandoffForm fields and skip re-asking known info.", "operationId": "get_lead_info_endpoint_chat_lead_info__session_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/chat/feedback/{message_id}": { "post": { "tags": [ "chat" ], "summary": "Submit Feedback Endpoint", "description": "Submit feedback (thumbs up/down) for a specific bot reply. Also scores the Langfuse trace if available.", "operationId": "submit_feedback_endpoint_chat_feedback__message_id__post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Message Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/chat/history/{session_id}": { "get": { "tags": [ "chat" ], "summary": "Get History Endpoint", "description": "Retrieve chat history for a given session.\n\nAccepts both admin auth (X-API-Key / X-Operator-Key) and widget auth (X-Bot-Key).\nSupports cursor-based pagination via `before` param.", "operationId": "get_history_endpoint_chat_history__session_id__get", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } }, { "name": "before", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Cursor \u2014 return messages with id < this value (for pagination)", "title": "Before" }, "description": "Cursor \u2014 return messages with id < this value (for pagination)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Max messages to return", "default": 50, "title": "Limit" }, "description": "Max messages to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/chat/upload-url": { "post": { "tags": [ "chat" ], "summary": "Get Visitor Upload Url", "description": "Return a presigned B2 PUT URL so the widget can upload a file directly.\n\nAuth: X-Bot-Key header. The widget uploads via PUT (no auth needed) then\nsends the file_url over the live-chat WebSocket.", "operationId": "get_visitor_upload_url_chat_upload_url_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrlRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/chat/transcript": { "post": { "tags": [ "chat" ], "summary": "Send Chat Transcript", "description": "Send the chat transcript for a session to the visitor's email.\n\nAuth: X-Bot-Key header (widget).\nRate limit: 3 per minute per bot key to prevent abuse.", "operationId": "send_chat_transcript_chat_transcript_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptEmailRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/chat/connect-request/{session_id}": { "get": { "tags": [ "chat" ], "summary": "Get Pending Connect Request", "description": "Widget polls this while in bot mode to discover operator-initiated\nconnect invitations. Returns ``{ pending: false }`` when none.\n\nAuth: ``X-Bot-Key`` (visitor widget). The session must belong to the bot.", "operationId": "get_pending_connect_request_chat_connect_request__session_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/chat/connect-request/{session_id}/respond": { "post": { "tags": [ "chat" ], "summary": "Respond To Connect Request", "description": "Visitor accepts or declines an operator's connect-request.\n\nOn accept we atomically promote the session to live chat and assign it to\nthe requesting operator. On decline (or stale ``request_id``) we just\nconsume the pending entry \u2014 the bot conversation continues unchanged.", "operationId": "respond_to_connect_request_chat_connect_request__session_id__respond_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectRequestResponseBody" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents": { "get": { "tags": [ "documents" ], "summary": "Get Documents Endpoint", "description": "Retrieve a list of all ingested documents for the authenticated client.", "operationId": "get_documents_endpoint_documents_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/pages": { "get": { "tags": [ "documents" ], "summary": "Get Document Pages Endpoint", "description": "Return all crawled page URLs for a website source, with per-page chunk counts and titles.", "operationId": "get_document_pages_endpoint_documents_pages_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "source", "in": "query", "required": true, "schema": { "type": "string", "description": "Normalized root domain (e.g. fynix.digital)", "title": "Source" }, "description": "Normalized root domain (e.g. fynix.digital)" }, { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPagesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/documents/{document_name}": { "delete": { "tags": [ "documents" ], "summary": "Delete Document Endpoint", "description": "Delete all documents associated with a document name for the authenticated client.", "operationId": "delete_document_endpoint_documents__document_name__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "document_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Name" } }, { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/ingest": { "post": { "tags": [ "documents" ], "summary": "Ingest Documents", "description": "Ingest multiple files (PDF, DOCX, TXT, MD) for a client.\n\nSubscription-gated \u2014 uploading new content into the knowledge base is\na paid-feature action. Customers with an expired trial can still see\nand delete what they already uploaded, just not add more until they\nreactivate.\n\nCredit-metered at ``credit_cost.document_upload`` per file (default 2).\nCost is calculated against the post-validation file count so unsupported\nextensions and oversize files don't burn credits. Deduction happens\nBEFORE the disk write so we never persist a file we can't bill for; if\na write later fails, the per-file cost is refunded.", "operationId": "ingest_documents_ingest_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_ingest_documents_ingest_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/ingest/status/{job_id}": { "get": { "tags": [ "documents" ], "summary": "Ingest Status Endpoint", "description": "Poll the status of a background ingestion job.\n\nReturns the job's current state: queued, in_progress, complete, or failed.\nOnly available when WORKER_ENABLED=true (ARQ task queue).", "operationId": "ingest_status_endpoint_ingest_status__job_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/crawl/progress": { "get": { "tags": [ "documents" ], "summary": "Crawl Progress Endpoint", "description": "Return live progress + terminal status for the caller's crawl.\n\nPolled by the frontend every few seconds. Reads from Redis so the same\nstate is visible whether the crawl is running in this API process or in\nthe ARQ worker. The response always contains ``status`` (one of\n``\"idle\" | \"running\" | \"cancelling\" | \"cancelled\" | \"done\" | \"failed\"``)\nand ``urls`` (list of URLs discovered so far). When ``status=\"running\"``\nthe response also contains ``pages_crawled``, ``max_pages``,\n``current_url``, ``started_at`` (epoch seconds), and ``cancellable``\n(bool) so the UI can render a real progress bar, an ETA, and a Cancel\nbutton. When ``status=\"done\"`` / ``\"cancelled\"`` the response contains\n``result`` with the ingestion payload; when ``\"failed\"`` it contains\n``error``.", "operationId": "crawl_progress_endpoint_crawl_progress_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/crawl/cancel": { "post": { "tags": [ "documents" ], "summary": "Crawl Cancel Endpoint", "description": "Request cancellation of the caller's in-flight crawl.\n\nReturns 202 immediately. The orchestrator (running in the ARQ worker or\ninline) sees the cancel flag within ~1s, asks the crawler subprocess to\nstop cooperatively between URLs (fast, clean, no leaked Chromium), and\nfalls back to SIGTERM if the subprocess doesn't honour it within a few\nseconds. Any pages that were crawled before the cancel landed are still\ningested so we don't throw away work the customer already paid for.\n\nIdempotent: calling cancel twice is fine; the flag is a single Redis key\nthat auto-expires when the crawl finishes (or after ``CRAWL_SUBPROCESS\n_TIMEOUT + 60s`` if everything goes sideways).", "operationId": "crawl_cancel_endpoint_crawl_cancel_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/crawl/discover": { "post": { "tags": [ "documents" ], "summary": "Crawl Discover Endpoint", "description": "Discover the number of crawlable pages on a site without ingesting content.\n\nFetches robots.txt \u2192 sitemaps \u2192 falls back to a 1-level HTML BFS if no\nsitemap is found. Returns within ~20 seconds. Used by the frontend to show\n\"Found X pages. Ready to crawl?\" before the user commits to a full crawl.\n\nThe ``total_found`` count is capped at the caller's plan ``max_crawl_pages``\nceiling so the number is always actionable and never exceeds what the plan\nallows. ``capped=true`` signals that there may be more pages than shown.\n\nPaid plans (Starter/Standard) carry an UNLIMITED (-1) page cap because\ncrawling is metered purely by credits; for them the discovery query falls\nback to a fixed 1000-URL ceiling so the preview stays bounded.", "operationId": "crawl_discover_endpoint_crawl_discover_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlDiscoverRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/crawl/diff": { "post": { "tags": [ "documents" ], "summary": "Crawl Diff Endpoint", "description": "Diff a recrawl against the existing knowledge base for the given source.\n\nRuns the same robots.txt \u2192 sitemap \u2192 BFS discovery as ``/crawl/discover`` and\ncompares the resulting URL set against the pages already stored under\n``replace_source`` for this bot/client. Returns exact counts: ``unchanged``\n(URL present in both), ``new_pages`` (in sitemap but not stored), and\n``removed_pages`` (stored but no longer in sitemap).\n\nNotes:\n* URL-level diff only \u2014 actual content changes are detected per-page during\n the crawl itself via the SHA-256 dedup hash in the ingestion pipeline. This\n endpoint is fast (no page fetches) and is purely for the pre-recrawl\n confirmation UI.\n* Numbers are exact within the discovery cap; if ``capped`` is true the\n sitemap exceeded the plan ceiling and only the first ``plan_max`` URLs\n were considered.", "operationId": "crawl_diff_endpoint_crawl_diff_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlDiffRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/crawl": { "post": { "tags": [ "documents" ], "summary": "Crawl Endpoint", "description": "Start a crawl + ingestion job for a client.\n\nThe actual crawl runs in the ARQ worker (or as a FastAPI BackgroundTask\nwhen WORKER_ENABLED=false), so this endpoint returns 202 immediately\nwith a ``job_id``. Callers poll ``GET /crawl/progress`` to read live URL\ndiscovery and the terminal ``done`` / ``failed`` state.", "operationId": "crawl_endpoint_crawl_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlRequest" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/analytics/qualification-funnel": { "get": { "tags": [ "analytics" ], "summary": "Get Qualification Funnel", "operationId": "get_qualification_funnel_analytics_qualification_funnel_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": true, "schema": { "type": "integer", "title": "Bot Id" } }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "description": "7d|30d|90d|all", "default": "30d", "title": "Period" }, "description": "7d|30d|90d|all" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/analytics/dashboard": { "get": { "tags": [ "analytics" ], "summary": "Get Dashboard Analytics Endpoint", "description": "Retrieve live aggregate statistics for the admin dashboard.", "operationId": "get_dashboard_analytics_endpoint_analytics_dashboard_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } }, { "name": "days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 365, "minimum": 1 }, { "type": "null" } ], "description": "Restrict stats to the last N days", "title": "Days" }, "description": "Restrict stats to the last N days" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/analytics/activity": { "get": { "tags": [ "analytics" ], "summary": "Get Activity Analytics Endpoint", "description": "Retrieve message activity over time for charts.", "operationId": "get_activity_analytics_endpoint_analytics_activity_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/analytics/top-questions": { "get": { "tags": [ "analytics" ], "summary": "Get Top Questions Endpoint", "description": "Retrieve the most common user queries.", "operationId": "get_top_questions_endpoint_analytics_top_questions_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/analytics/visitors": { "get": { "tags": [ "analytics" ], "summary": "Get Visitors Endpoint", "description": "Retrieve visitor sessions for the admin dashboard (most-recent first, paginated).", "operationId": "get_visitors_endpoint_analytics_visitors_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 500, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/analytics/ratings-summary": { "get": { "tags": [ "analytics" ], "summary": "Get Ratings Summary Endpoint", "description": "Retrieve post-chat visitor rating summary (avg, total, distribution).", "operationId": "get_ratings_summary_endpoint_analytics_ratings_summary_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/analytics/resolution-summary": { "get": { "tags": [ "analytics" ], "summary": "Get Resolution Summary Endpoint", "description": "Retrieve post-chat visitor resolution summary (resolved, unresolved, rate).", "operationId": "get_resolution_summary_endpoint_analytics_resolution_summary_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/analytics/feedback": { "get": { "tags": [ "analytics" ], "summary": "Get Feedback Endpoint", "description": "Retrieve all feedback for the admin dashboard.", "operationId": "get_feedback_endpoint_analytics_feedback_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/leads": { "get": { "tags": [ "leads" ], "summary": "List Leads", "description": "List leads with BANT data, scores, and optional filters.", "operationId": "list_leads_leads_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } }, { "name": "tier", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "unqualified|mql|sal|sql", "title": "Tier" }, "description": "unqualified|mql|sal|sql" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "backward-compat alias for tier", "title": "Status" }, "description": "backward-compat alias for tier" }, { "name": "min_score", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 100, "minimum": 0 }, { "type": "null" } ], "title": "Min Score" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/leads/stats": { "get": { "tags": [ "leads" ], "summary": "Lead Stats", "description": "Aggregate lead stats: total, unqualified, MQL, SAL, and SQL counts.", "operationId": "lead_stats_leads_stats_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/leads/mark-all-viewed": { "post": { "tags": [ "leads" ], "summary": "Mark All Leads Viewed", "description": "Bulk-clear the unread flag on every lead for the caller's bot(s).\n\nMatches the `PATCH /offline-messages/{id} \u2192 read` UX \u2014 a single\n\"Mark all as read\" click on the Leads page drops the sidebar badge\nto zero without opening every drawer.", "operationId": "mark_all_leads_viewed_leads_mark_all_viewed_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/leads/{session_id}/view": { "post": { "tags": [ "leads" ], "summary": "Mark Lead Viewed", "description": "Mark a single lead as viewed. Idempotent \u2014 subsequent calls are no-ops.\n\nReturns 204 (no body) so the frontend can fire-and-forget on drawer open.", "operationId": "mark_lead_viewed_leads__session_id__view_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/leads/export": { "get": { "tags": [ "leads" ], "summary": "Export Leads Csv", "description": "Export leads as a CSV file download.", "operationId": "export_leads_csv_leads_export_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/leads/{session_id}": { "get": { "tags": [ "leads" ], "summary": "Get Lead Detail", "description": "Get full lead detail: BANT + contact info + chat history.", "operationId": "get_lead_detail_leads__session_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/departments": { "get": { "tags": [ "operators" ], "summary": "List Departments", "description": "List all departments for the authenticated client/operator.", "operationId": "list_departments_operators_departments_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] }, "post": { "tags": [ "operators" ], "summary": "Create Department", "description": "Create a new department.", "operationId": "create_department_operators_departments_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDepartmentRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/operators/departments/{department_id}": { "patch": { "tags": [ "operators" ], "summary": "Update Department", "description": "Update a department.", "operationId": "update_department_operators_departments__department_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "department_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Department Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDepartmentRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "operators" ], "summary": "Delete Department", "description": "Delete a department. Operators in this department are moved to no department.", "operationId": "delete_department_operators_departments__department_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "department_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Department Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators": { "get": { "tags": [ "operators" ], "summary": "List Operators", "description": "List all operators for the authenticated client/operator.", "operationId": "list_operators_operators_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/operators/create": { "post": { "tags": [ "operators" ], "summary": "Create Operator", "description": "Create a new operator with login credentials.", "operationId": "create_operator_operators_create_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOperatorRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/operators/{operator_id}": { "patch": { "tags": [ "operators" ], "summary": "Update Operator", "description": "Update an operator's profile (owner/admin only).", "operationId": "update_operator_operators__operator_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "operator_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Operator Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOperatorRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "operators" ], "summary": "Delete Operator", "description": "Delete an operator (owner/admin only).", "operationId": "delete_operator_operators__operator_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "operator_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Operator Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/handoff": { "post": { "tags": [ "operators" ], "summary": "Request Handoff", "description": "Visitor-initiated live chat request \u2014 runs through the state machine.\n\nThe state machine ``LiveChatAvailabilityService`` decides what the widget\nshould do based on the workspace's current live-chat reality (feature\nflag, operator presence, business hours, queue capacity). The endpoint\nreturns a structured response the widget reads to pick its UI mode:\n\n* ``suggested_action == \"route\"`` \u2014 queue + notify operators (current path)\n* ``suggested_action == \"wait\"`` \u2014 queue + tell widget to show queue UI\n with auto-fallback timer\n* ``suggested_action == \"offline_form\"`` \u2014 do NOT queue, tell widget to\n switch to the offline message form with the matching ``state`` as the\n fallback reason\n\nSide effects (audit log, webhook, email notifications) only fire when\nthe visitor will actually be queued \u2014 no point waking operators when the\nstate machine has already decided to fall back to the form.", "operationId": "request_handoff_operators_handoff_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HandoffRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/operators/cancel-handoff/{session_id}": { "post": { "tags": [ "operators" ], "summary": "Cancel Handoff", "description": "Visitor cancels a waiting handoff request, returning session to bot mode.\n\nCalled by the widget when the visitor clicks \"Cancel and return to AI chat\"\nwhile still in the waiting state, especially if the WebSocket hasn't connected yet.", "operationId": "cancel_handoff_operators_cancel_handoff__session_id__post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/session-status/{session_id}": { "get": { "tags": [ "operators" ], "summary": "Get Session Live Status", "description": "Get the current live chat status for a session.\n\nCalled by the widget on mount to restore chatMode across page navigations.\nReturns the session status and operator name if assigned.", "operationId": "get_session_live_status_operators_session_status__session_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/queue": { "get": { "tags": [ "operators" ], "summary": "Get Queue", "description": "Get waiting chat queue from DB source-of-truth with visitor info.", "operationId": "get_queue_operators_queue_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/operators/accept/{session_id}": { "post": { "tags": [ "operators" ], "summary": "Accept Chat", "description": "Operator accepts a waiting chat.", "operationId": "accept_chat_operators_accept__session_id__post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AcceptChatRequest" }, { "type": "null" } ], "title": "Request" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/close/{session_id}": { "post": { "tags": [ "operators" ], "summary": "Close Chat", "description": "Operator closes a live chat.", "operationId": "close_chat_operators_close__session_id__post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/transfer/{session_id}": { "post": { "tags": [ "operators" ], "summary": "Transfer Chat", "description": "Transfer a live chat to another operator or department.", "operationId": "transfer_chat_operators_transfer__session_id__post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/me/status": { "get": { "tags": [ "operators" ], "summary": "Get My Operator Status", "description": "Get the current operator's online status. Used by the admin dashboard on mount.", "operationId": "get_my_operator_status_operators_me_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/operators/status": { "post": { "tags": [ "operators" ], "summary": "Set Operator Status", "description": "Set operator online/offline status explicitly.\n\nAccepts ``{\"is_online\": true/false}`` in the request body.\nFalls back to toggle behavior (backward compat) when no body is provided.\n\nWhen an operator transitions to offline, any sessions still assigned to\nthem are immediately re-queued and the affected visitors are notified \u2014\notherwise the visitor's widget would stay glued to a dead live session.", "operationId": "set_operator_status_operators_status_post", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SetStatusRequest" }, { "type": "null" } ], "title": "Request" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/operators/session/{session_id}/details": { "get": { "tags": [ "operators" ], "summary": "Get Session Details", "description": "Get full visitor/session details for the operator sidebar.", "operationId": "get_session_details_operators_session__session_id__details_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/session/{session_id}/qualification": { "patch": { "tags": [ "operators" ], "summary": "Override Qualification Dimension", "description": "Manually correct or reset one qualification dimension's score (BR-03).\n\nThe automated extraction path (``rag_service._background_bant_extraction``)\ndeliberately never downgrades a dimension's score, and budget/authority\nscores never decay \u2014 by design, so a weak follow-up can't erase a strong\nearlier signal. But that also means a single false-positive extraction, or\na visitor typing an implausible statement in bad faith (\"we have a\n$50k/month budget approved\"), permanently misclassifies a lead with no\nremedy short of direct database editing. This gives operators an audited\nway to correct or reset (score=0) a dimension without weakening the\nnever-downgrade guarantee for the automated path \u2014 every override is\nstill logged as an append-only ``BANTSignal`` row, same as an LLM or\nCTA-click signal, just tagged ``source=\"operator_override\"``.", "operationId": "override_qualification_dimension_operators_session__session_id__qualification_patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualificationOverrideRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/departments/public": { "get": { "tags": [ "operators" ], "summary": "List Departments Public", "description": "List departments for a bot (used by widget to show department picker).", "operationId": "list_departments_public_operators_departments_public_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/operators/upload-chat-file": { "post": { "tags": [ "operators" ], "summary": "Upload Chat File Route", "description": "Upload a file during live chat. Returns a URL to embed in messages.", "operationId": "upload_chat_file_route_operators_upload_chat_file_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_chat_file_route_operators_upload_chat_file_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/sessions/{session_id}/rating": { "post": { "tags": [ "operators" ], "summary": "Submit Visitor Rating", "description": "Record a visitor's post-chat satisfaction rating and resolution status.\n\nAuth: X-Bot-Key header (widget). Both fields are optional \u2014 subsequent\ncalls silently overwrite previous values.", "operationId": "submit_visitor_rating_operators_sessions__session_id__rating_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VisitorRatingRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/qualified-bot-sessions/debug": { "get": { "tags": [ "operators" ], "summary": "Debug Qualified Bot Sessions", "description": "Diagnostic view \u2014 returns every session in this workspace alongside the\nfields the qualifier evaluates so we can see why a row didn't surface.\n\nStrictly admin-only; not consumed by the UI. Useful when a session you\nexpected to see in \"Chatting with AI\" is missing \u2014 usually because the\nstatus moved off ``bot`` or the BANT signals never landed in the\nexpected columns.", "operationId": "debug_qualified_bot_sessions_operators_qualified_bot_sessions_debug_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/operators/qualified-bot-sessions": { "get": { "tags": [ "operators" ], "summary": "Get Qualified Bot Sessions", "description": "List visitors who are **currently** chatting with the AI and whose\nBANT qualification has captured at least 2 of 4 dimensions.\n\n\"Currently\" is enforced by a real-time presence heartbeat \u2014 the widget\npings the connect-request endpoint every 5s while in bot mode, and the\nin-memory manager tracks which sessions have a fresh ping. As soon as\nthe visitor closes the tab or navigates away, polling stops and the row\nauto-drops off the list within seconds. No time-window heuristic, no\nabandoned tabs ever shown.", "operationId": "get_qualified_bot_sessions_operators_qualified_bot_sessions_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/connect-request/{session_id}": { "post": { "tags": [ "operators" ], "summary": "Operator Connect Request", "description": "Operator asks a bot-mode visitor whether they'd like to switch to a\nlive conversation. The visitor sees a Yes/No popup; nothing changes\nserver-side until they accept (then the takeover transition fires).\n\nIdempotent re-issuing for the same session simply refreshes the popup \u2014\ne.g. operator clicks Connect twice. The visitor only ever sees the latest\noperator's name.", "operationId": "operator_connect_request_operators_connect_request__session_id__post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AcceptChatRequest" }, { "type": "null" } ], "title": "Request" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/connect-request/{session_id}/cancel": { "post": { "tags": [ "operators" ], "summary": "Operator Cancel Connect Request", "description": "Operator cancels a pending connect-request before the visitor responds.", "operationId": "operator_cancel_connect_request_operators_connect_request__session_id__cancel_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/takeover/{session_id}": { "post": { "tags": [ "operators" ], "summary": "Takeover Bot Session", "description": "Proactively take over a session currently being handled by the AI.\n\nDistinct from ``/accept`` which only claims sessions already in the\n``waiting`` queue. Takeover transitions ``status='bot' \u2192 'live'`` atomically\nso two operators can't take over the same visitor at once.", "operationId": "takeover_bot_session_operators_takeover__session_id__post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AcceptChatRequest" }, { "type": "null" } ], "title": "Request" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/operators/push/vapid-public-key": { "get": { "tags": [ "operators" ], "summary": "Get Vapid Public Key", "description": "Return the server's VAPID public key (URL-safe base64).\n\nPublic information \u2014 the frontend uses it as ``applicationServerKey`` when\ncalling ``pushManager.subscribe()``. Safe to expose without auth, but we\nkeep it on the operator router so the SDK call lives next to the rest of\nthe push surface.", "operationId": "get_vapid_public_key_operators_push_vapid_public_key_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/operators/push/subscribe": { "post": { "tags": [ "operators" ], "summary": "Push Subscribe", "description": "Register a Web Push subscription for the calling user.\n\nAccepts both operator and workspace-owner (client) logins. The row's\n``operator_id`` or ``client_id`` is set depending on the auth type \u2014 a DB\nCHECK constraint guarantees exactly one is populated. Upsert by\n``endpoint`` so the same browser re-subscribing simply re-binds to the\ncurrent account (e.g. after re-login from the same machine, possibly as\na different role).", "operationId": "push_subscribe_operators_push_subscribe_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushSubscribeRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] }, "delete": { "tags": [ "operators" ], "summary": "Push Unsubscribe", "description": "Remove a Web Push subscription previously registered for this user.\n\nThe frontend calls this when the user manually disables notifications or\nafter ``pushManager.unsubscribe()`` returns. Idempotent: a delete on a\nnon-existent endpoint is a no-op. Scoped to the calling user's own row \u2014\na subscriber cannot delete another account's subscription even if they\nhappen to know the endpoint.", "operationId": "push_unsubscribe_operators_push_subscribe_delete", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushSubscribeRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/offline-messages": { "post": { "tags": [ "offline-messages" ], "summary": "Submit Offline Message", "description": "Submit an offline message (called by widget when no agent is available).", "operationId": "submit_offline_message_offline_messages_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitOfflineMessageRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "offline-messages" ], "summary": "List Offline Messages", "description": "List offline messages for the authenticated client/agent's bots.", "operationId": "list_offline_messages_offline_messages_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/offline-messages/{message_id}": { "patch": { "tags": [ "offline-messages" ], "summary": "Update Offline Message", "description": "Update an offline message status (mark as read/replied).", "operationId": "update_offline_message_offline_messages__message_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Message Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOfflineMessageRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "offline-messages" ], "summary": "Delete Offline Message", "description": "Delete an offline message.", "operationId": "delete_offline_message_offline_messages__message_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Message Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/canned-responses": { "get": { "tags": [ "canned-responses" ], "summary": "List Canned Responses", "description": "List canned responses for the client.", "operationId": "list_canned_responses_canned_responses_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "canned-responses" ], "summary": "Create Canned Response", "description": "Create a new canned response.", "operationId": "create_canned_response_canned_responses_post", "security": [ { "APIKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCannedResponseRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/canned-responses/{response_id}": { "patch": { "tags": [ "canned-responses" ], "summary": "Update Canned Response", "description": "Update a canned response.", "operationId": "update_canned_response_canned_responses__response_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Response Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCannedResponseRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "canned-responses" ], "summary": "Delete Canned Response", "description": "Delete a canned response.", "operationId": "delete_canned_response_canned_responses__response_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Response Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/notifications": { "get": { "tags": [ "notifications" ], "summary": "List Notifications", "operationId": "list_notifications_notifications_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 30, "title": "Limit" } }, { "name": "before_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Before Id" } }, { "name": "unread_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Unread Only" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "notifications" ], "summary": "Clear All", "operationId": "clear_all_notifications_delete", "security": [ { "APIKeyHeader": [] } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/notifications/unread-count": { "get": { "tags": [ "notifications" ], "summary": "Get Unread Count", "operationId": "get_unread_count_notifications_unread_count_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/notifications/mark-all-read": { "post": { "tags": [ "notifications" ], "summary": "Mark All Read", "operationId": "mark_all_read_notifications_mark_all_read_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/notifications/{notification_id}/read": { "patch": { "tags": [ "notifications" ], "summary": "Mark Read", "operationId": "mark_read_notifications__notification_id__read_patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "notification_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Notification Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/notifications/{notification_id}": { "delete": { "tags": [ "notifications" ], "summary": "Delete One", "operationId": "delete_one_notifications__notification_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "notification_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Notification Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/client/settings": { "get": { "tags": [ "client" ], "summary": "Get Client Settings", "description": "Retrieve chatbot customization settings.", "operationId": "get_client_settings_client_settings_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "client" ], "summary": "Update Client Settings", "description": "Update chatbot customization settings.", "operationId": "update_client_settings_client_settings_patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientSettingsUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/client/feedback": { "get": { "tags": [ "client" ], "summary": "List My Feedback", "description": "List the logged-in client's own platform feedback, newest first.\n\nIncludes the resolution ``status`` and the superadmin's ``admin_response``\nso the customer can see that their issue was handled.", "operationId": "list_my_feedback_client_feedback_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] }, "post": { "tags": [ "client" ], "summary": "Submit Platform Feedback", "description": "Save a classified feedback entry from an admin dashboard user.", "operationId": "submit_platform_feedback_client_feedback_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformFeedbackCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/client/feedback/upload": { "post": { "tags": [ "client" ], "summary": "Upload Feedback Attachment", "description": "Upload a feedback attachment (max 10MB) to R2 and return the URL.", "operationId": "upload_feedback_attachment_client_feedback_upload_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_feedback_attachment_client_feedback_upload_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/client/upload-logo": { "post": { "tags": [ "client" ], "summary": "Upload Logo Endpoint", "description": "Upload a logo to Backblaze B2 and return the URL.", "operationId": "upload_logo_endpoint_client_upload_logo_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_logo_endpoint_client_upload_logo_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/client/profile": { "patch": { "tags": [ "client" ], "summary": "Update Client Profile", "description": "Update the authenticated client's display name.\n\nEmail changes go through /client/change-email/* instead \u2014 that flow\nrequires the current password and confirms ownership of the new inbox\nvia OTP before the login email actually moves.", "operationId": "update_client_profile_client_profile_patch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientProfilePatch" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/client/change-password": { "post": { "tags": [ "client" ], "summary": "Change Client Password", "description": "Change the authenticated client's password (verifies the current one).", "operationId": "change_client_password_client_change_password_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/client/change-email/request": { "post": { "tags": [ "client" ], "summary": "Request Client Email Change", "description": "Start an email change: verify the current password, then OTP-verify the new inbox.\n\nThe login email is NOT updated here \u2014 it only moves once\n``/change-email/confirm`` validates the code sent to ``new_email``. The\ncurrent (old) address also gets a notice, so an attacker who has\nhijacked the session can't quietly redirect account recovery without\nthe real owner finding out.", "operationId": "request_client_email_change_client_change_email_request_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeEmailRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/client/change-email/confirm": { "post": { "tags": [ "client" ], "summary": "Confirm Client Email Change", "description": "Verify the OTP sent to the pending new email and promote it to the login email.", "operationId": "confirm_client_email_change_client_change_email_confirm_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeEmailConfirm" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/client/change-email/cancel": { "post": { "tags": [ "client" ], "summary": "Cancel Client Email Change", "description": "Abandon a pending email change before it's confirmed.", "operationId": "cancel_client_email_change_client_change_email_cancel_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/client/api-key": { "get": { "tags": [ "client" ], "summary": "Get Client Api Key", "description": "Return the authenticated client's API key in masked form.", "operationId": "get_client_api_key_client_api_key_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/client/api-key/regenerate": { "post": { "tags": [ "client" ], "summary": "Regenerate Client Api Key", "description": "Rotate the client's API key. Returns the full new key ONCE for copy.", "operationId": "regenerate_client_api_key_client_api_key_regenerate_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/webhooks": { "get": { "tags": [ "webhooks" ], "summary": "List Webhooks", "operationId": "list_webhooks_webhooks_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": true, "schema": { "type": "integer", "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "webhooks" ], "summary": "Create Webhook", "operationId": "create_webhook_webhooks_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": true, "schema": { "type": "integer", "title": "Bot Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/webhooks/{webhook_id}": { "patch": { "tags": [ "webhooks" ], "summary": "Update Webhook", "operationId": "update_webhook_webhooks__webhook_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Webhook Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "webhooks" ], "summary": "Delete Webhook", "operationId": "delete_webhook_webhooks__webhook_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Webhook Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/webhooks/{webhook_id}/deliveries": { "get": { "tags": [ "webhooks" ], "summary": "Get Webhook Deliveries", "operationId": "get_webhook_deliveries_webhooks__webhook_id__deliveries_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Webhook Id" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/webhooks/{webhook_id}/test": { "post": { "tags": [ "webhooks" ], "summary": "Test Webhook", "operationId": "test_webhook_webhooks__webhook_id__test_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Webhook Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/subscriptions/plans": { "get": { "tags": [ "subscriptions" ], "summary": "List Plans", "description": "Return all active plans for the pricing page. No auth required.", "operationId": "list_plans_subscriptions_plans_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/subscriptions/start-trial": { "post": { "tags": [ "subscriptions" ], "summary": "Start Trial Endpoint", "description": "Begin a 14-day free trial of the named paid plan.\n\nTriggered when the customer clicks \"Start free trial\" on Starter or\nStandard. No card is required; on day 14 the expiry cron (PR4) flips\nthe subscription to ``trial_expired`` and the customer must pick a\nplan + enter a card to keep their bot live.\n\nTrial credits = the plan's full ``credits_per_month`` so the prospect\nexperiences the real product. The welcome email fires here, not on\nregistration, since registration now lands the customer on the free\ntier without a trial.\n\nError mapping (matches :class:`TrialUnavailable.reason`):\n\n* ``plan_not_found`` \u2192 404\n* ``plan_not_trialable`` \u2192 400\n* ``already_trialed`` \u2192 409\n* ``active_paid_subscription`` \u2192 409", "operationId": "start_trial_endpoint_subscriptions_start_trial_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartTrialRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/subscriptions/current": { "get": { "tags": [ "subscriptions" ], "summary": "Get Current Subscription", "description": "Return the client's current subscription details + plan info.", "operationId": "get_current_subscription_subscriptions_current_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/subscriptions/geo": { "get": { "tags": [ "subscriptions" ], "summary": "Get Billing Geo", "description": "Return the geo / currency profile the UI should render against.\n\nSingle call so the Billing page and PlanModal don't have to fan out a\nper-plan quote \u2014 the frontend converts INR paise to its local USD with\nthe returned ``display_rate`` (a paid plan's INR price is the source of\ntruth; USD is informational until international payments is live).\n\nIncludes the Razorpay public key so the React layer doesn't have to\nre-stuff it from a separate env / endpoint when opening the modal.", "operationId": "get_billing_geo_subscriptions_geo_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/subscriptions/verify-razorpay-subscription": { "post": { "tags": [ "subscriptions" ], "summary": "Verify Razorpay Subscription", "description": "Verify the Razorpay Checkout return signature for a subscription.\n\nRazorpay's ``subscription.activated`` webhook is the canonical reconciler\n\u2014 this endpoint only exists so the UI can flip to a \"Subscription\nactive\" state the moment the modal closes, without waiting for the\nout-of-band webhook round-trip.\n\nFailure modes (caller-facing):\n * 400 \u2014 signature mismatch (replay / tampering).\n * 502 \u2014 Razorpay SDK error (network / quota).", "operationId": "verify_razorpay_subscription_subscriptions_verify_razorpay_subscription_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRazorpaySubscriptionRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/subscriptions/usage": { "get": { "tags": [ "subscriptions" ], "summary": "Get Subscription Usage", "description": "Backward-compat redirect to the credit-balance endpoint.\n\nThe legacy per-metric usage summary has been retired in favour of the\ncredit ledger. Kept here as a thin shim so older admin builds and any\nexternal consumers don't 404.", "operationId": "get_subscription_usage_subscriptions_usage_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/subscriptions/invoices": { "get": { "tags": [ "subscriptions" ], "summary": "List Invoices", "description": "Return the client's payment history (most recent first).", "operationId": "list_invoices_subscriptions_invoices_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/subscriptions/billing-details": { "get": { "tags": [ "subscriptions" ], "summary": "Get Billing Details", "description": "The buyer identity used on tax invoices (invoicing v2 Phase 1).", "operationId": "get_billing_details_subscriptions_billing_details_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] }, "put": { "tags": [ "subscriptions" ], "summary": "Update Billing Details", "operationId": "update_billing_details_subscriptions_billing_details_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingDetailsBody" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/subscriptions/checkout/quote": { "get": { "tags": [ "subscriptions" ], "summary": "Checkout Quote", "description": "Single source of truth for what the checkout button will charge.\n\nThe admin UI calls this before opening any payment modal so it can\nrender the right currency, amount, payment methods, and CTA \u2014 without\nthe frontend having to know provider routing rules.\n\nResponse shape (always 200 unless inputs are invalid):\n\n``{\n \"country\": \"IN\" | \"US\" | null,\n \"currency\": \"INR\" | \"USD\",\n \"amount_minor\": 149900,\n \"amount_display\": \"\u20b91,499\",\n \"billing_cycle\": \"monthly\",\n \"provider\": \"razorpay\",\n \"methods\": [\"card\", \"upi\"],\n \"checkout_supported\": true, # false \u2192 render Contact Sales\n \"contact_sales\": null | \"developer@oyechats.com\",\n}``\n\nA ``checkout_supported: false`` response carries ``contact_sales`` so\nthe UI can surface a CTA instead of an empty button.", "operationId": "checkout_quote_subscriptions_checkout_quote_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "plan_id", "in": "query", "required": true, "schema": { "type": "integer", "title": "Plan Id" } }, { "name": "billing_cycle", "in": "query", "required": false, "schema": { "type": "string", "default": "monthly", "title": "Billing Cycle" } }, { "name": "billing_country", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Billing Country" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/subscriptions/admin/plan-price-check": { "get": { "tags": [ "subscriptions" ], "summary": "Plan Price Check", "description": "Super-admin diagnostic: local plan price vs the live Razorpay plan amount.\n\nThe checkout disclosure quotes ``plan.monthly_price_cents``; if it drifts\nfrom the amount configured on the live Razorpay plan, the UI quotes a rupee\nfigure the mandate will not debit. This surfaces drift per plan/cycle. A\nRazorpay error on any plan yields ``in_sync: null`` + an error string \u2014 a\ndiagnostic must never 500.", "operationId": "plan_price_check_subscriptions_admin_plan_price_check_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/subscriptions/checkout": { "post": { "tags": [ "subscriptions" ], "summary": "Create Checkout", "description": "Create a Razorpay checkout session for a paid plan.\n\nReturns ``{provider, subscription_id, key_id, name, description, prefill, theme}``\n\u2014 frontend opens ``new Razorpay({subscription_id, ...}).open()``.", "operationId": "create_checkout_subscriptions_checkout_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/subscriptions/change-plan": { "post": { "tags": [ "subscriptions" ], "summary": "Change Plan", "description": "Upgrade or downgrade the client's subscription to a different plan.\n\nResponse shape \u2014 the frontend branches on which key is present:\n\n* ``{\"status\": \"checkout_required\", ...}`` \u2014 Razorpay subscription auth required\n* ``{\"status\": \"downgrade_scheduled\", ...}`` \u2014 scheduled for next cycle\n* ``{\"status\": \"downgraded\", \"message\": \"...\"}`` \u2014 Free downgrade", "operationId": "change_plan_subscriptions_change_plan_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePlanRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/subscriptions/cancel-scheduled-change": { "post": { "tags": [ "subscriptions" ], "summary": "Cancel Scheduled Change Endpoint", "description": "Clear a queued downgrade so the customer stays on their current plan.\n\nIdempotent: returns ``{\"status\": \"no_change_pending\"}`` when nothing is\nqueued. When a change WAS queued, this resets ``scheduled_*`` to NULL and\nleaves ``cancel_at_period_end`` alone \u2014 the gateway mandate was cancelled\nat-cycle-end when the downgrade was scheduled, so the customer must\nre-authorise to keep the current plan past cycle end. We surface that as\n``mandate_action`` in the response so the frontend can prompt accordingly.", "operationId": "cancel_scheduled_change_endpoint_subscriptions_cancel_scheduled_change_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/subscriptions/cancel": { "post": { "tags": [ "subscriptions" ], "summary": "Cancel Subscription", "description": "Cancel the client's subscription at the end of the current billing period.\n\nCalls the upstream provider's cancel-at-cycle-end API; the local row is\nonly marked ``cancel_at_period_end=True`` until the provider's webhook\nfires the actual cancellation. Pass ``bot_id`` to cancel a specific bot's\nsubscription under the per-bot model (N3); omit it to act on the account.", "operationId": "cancel_subscription_subscriptions_cancel_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelSubscriptionRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/subscriptions/resume": { "post": { "tags": [ "subscriptions" ], "summary": "Resume Subscription", "description": "Resume a subscription that was scheduled for cancellation.\n\n``/cancel`` issues the Razorpay cancel IMMEDIATELY with\n``cancel_at_cycle_end=1`` (``razorpay_service.cancel_subscription(sub,\nat_period_end=True)``) before flipping the local ``cancel_at_period_end``\nflag. Razorpay has NO un-cancel / resume API for an at-cycle-end-cancelled\nsubscription, so merely clearing the local flags would LIE: the gateway\nstill cancels at period end \u2192 involuntary churn while the UI says\n\"resumed\" (BL-3).\n\nSo we mirror the honest sibling ``cancel_scheduled_change_endpoint``:\nbecause the mandate is dead at the gateway, we re-authorise by minting a\nFRESH Razorpay subscription for the same plan/cycle (tagging the\npredecessor via ``prev_razorpay_subscription_id`` so it is retired at the\nnew sub's activation webhook) and return ``mandate_action:\n\"reauthorise_required\"`` with the checkout payload. We do NOT clear the\nlocal cancel flags or claim success here \u2014 the row must not pretend the\ncancellation was undone until the customer actually re-authorises and the\nactivation webhook lands.\n\nPass ``bot_id`` to resume a specific bot's subscription (N3); omit to act on\nthe account's highest-tier subscription.", "operationId": "resume_subscription_subscriptions_resume_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeSubscriptionRequest", "default": {} } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/subscriptions/seats": { "post": { "tags": [ "subscriptions" ], "summary": "Change Seat Count", "description": "Add or remove operator seats from the active subscription.\n\nEach seat above ``plan.included_operator_seats`` is billed through a\nSEPARATE Razorpay add-on subscription (``RAZORPAY_SEAT_PLAN_ID``, whose\nplan amount IS the per-seat price). The main plan subscription is never\nedited for seats \u2014 Razorpay ``quantity`` multiplies the WHOLE plan\namount, which would overcharge the customer (P0-3). The local\n``operator_quantity`` mirror is updated immediately so live-chat seat\nenforcement sees the new limit without webhook latency.", "operationId": "change_seat_count_subscriptions_seats_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatChangeRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/credits/balance": { "get": { "tags": [ "credits" ], "summary": "Get Credit Balance", "description": "Return everything the Billing page needs in one round-trip:\n\n* Current credit balance (plan + top-up + soonest expiry).\n* Monthly grant + reset date (driven by the active subscription period).\n* Per-action credit costs from ``pricing_config`` so the UI can render\n \"1 AI chat = 1 credit\" without baking the values in.\n* This-period usage (count of chats / URL crawls / customer emails the\n customer has consumed since the last ``plan_grant``). Useful for the\n \"How you're using credits\" panel.\n* Currency display info (symbol + code) so localisation is centralised.", "operationId": "get_credit_balance_credits_balance_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/credits/history": { "get": { "tags": [ "credits" ], "summary": "Get Credit History", "description": "Return paginated ledger entries for the client (most recent first).", "operationId": "get_credit_history_credits_history_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "title": "Page" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/credits/topup": { "post": { "tags": [ "credits" ], "summary": "Initiate Topup", "description": "Initiate a top-up purchase via Razorpay.\n\nReturns a Razorpay order payload:\n``{provider, order_id, amount, currency, key_id, name, description, prefill, theme}``\n\u2014 frontend opens ``new Razorpay({order_id, ...}).open()``.\n\nCredits are granted asynchronously via the Razorpay webhook on payment\ncapture; the frontend should also call ``/credits/topup/verify`` so the\nsuccess modal is signature-verified server-side before showing confetti\n(defence-in-depth against tampered callbacks).", "operationId": "initiate_topup_credits_topup_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/credits/topup/verify": { "post": { "tags": [ "credits" ], "summary": "Verify Topup Payment", "description": "Verify a Razorpay Checkout success callback and reconcile the grant.\n\nThe credit grant normally lands via the ``payment.captured`` / ``order.paid``\nwebhook. This endpoint signature-verifies the modal callback and then runs\nan idempotent reconcile (L3) so a dropped webhook still credits the customer\ninstead of leaving them paid-but-no-credits.", "operationId": "verify_topup_payment_credits_topup_verify_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupVerifyRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/credits/packs": { "get": { "tags": [ "credits" ], "summary": "List Topup Packs", "description": "Public list of currently-offered top-up packs (no auth).", "operationId": "list_topup_packs_credits_packs_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/public/pricing-catalog": { "get": { "tags": [ "public-pricing" ], "summary": "Pricing Catalog", "operationId": "pricing_catalog_public_pricing_catalog_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/superadmin/plans": { "get": { "tags": [ "superadmin-plans" ], "summary": "List All Plans", "description": "List all plans including inactive ones (for admin management).", "operationId": "list_all_plans_superadmin_plans_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] }, "post": { "tags": [ "superadmin-plans" ], "summary": "Create Plan", "description": "Create a new pricing plan.", "operationId": "create_plan_superadmin_plans_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlanRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/plans/{plan_id}": { "put": { "tags": [ "superadmin-plans" ], "summary": "Update Plan", "description": "Update an existing plan. Only provided fields are modified.", "operationId": "update_plan_superadmin_plans__plan_id__put", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "plan_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Plan Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePlanRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "superadmin-plans" ], "summary": "Delete Plan", "description": "Soft-delete a plan (set is_active=False). Cannot delete plans with active subscriptions.", "operationId": "delete_plan_superadmin_plans__plan_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "plan_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Plan Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/pricing-content": { "get": { "tags": [ "superadmin-plans" ], "summary": "Read Pricing Content", "description": "Editable website pricing copy (FAQ, comparison matrix, top-ups, costs).", "operationId": "read_pricing_content_superadmin_pricing_content_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] }, "put": { "tags": [ "superadmin-plans" ], "summary": "Write Pricing Content", "description": "Upsert any subset of the website pricing-content blobs.", "operationId": "write_pricing_content_superadmin_pricing_content_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingContentRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/subscriptions": { "get": { "tags": [ "superadmin-plans" ], "summary": "List Subscriptions", "description": "List all subscriptions with optional status/plan filters.", "operationId": "list_subscriptions_superadmin_subscriptions_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "plan_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Plan Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/subscriptions/{subscription_id}": { "put": { "tags": [ "superadmin-plans" ], "summary": "Update Subscription", "description": "Manual override: change plan, status, extend trial, etc.", "operationId": "update_subscription_superadmin_subscriptions__subscription_id__put", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Subscription Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/revenue": { "get": { "tags": [ "superadmin-plans" ], "summary": "Get Revenue Metrics", "description": "Calculate MRR, total revenue, and subscription counts.\n\nAll monetary figures are reported in **USD cents** (the dashboard's\ncanonical currency). Plan prices and invoices stored in INR are converted\nvia the same fixed-rate rule the customer app uses for non-Indian visitors.", "operationId": "get_revenue_metrics_superadmin_revenue_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/clients/{client_id}/credits": { "post": { "tags": [ "superadmin-v2" ], "summary": "Grant Credits", "operationId": "grant_credits_superadmin_clients__client_id__credits_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Client Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsGrant" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/clients/{client_id}/impersonate": { "post": { "tags": [ "superadmin-v2" ], "summary": "Impersonate", "operationId": "impersonate_superadmin_clients__client_id__impersonate_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Client Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/impersonation/{token_id}/revoke": { "post": { "tags": [ "superadmin-v2" ], "summary": "Revoke Impersonation", "description": "Revoke an impersonation token server-side (audit F16).\n\nMarks ``revoked_at`` on the ``impersonation_tokens`` row so the token can\nno longer be redeemed \u2014 any redemption path MUST require\n``revoked_at IS NULL AND expires_at > now()``. The raw token itself never\nreaches this endpoint; revocation is by row id, so the dashboard can exit\nwithout holding the sensitive credential.\n\nAuthorization: the super-admin who issued the token may always revoke it\n(including read-only admins \u2014 revocation strictly reduces privilege);\nrevoking another admin's token requires a write-capable super-admin role.\nIdempotent: revoking an already-revoked token is a no-op success.", "operationId": "revoke_impersonation_superadmin_impersonation__token_id__revoke_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "token_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Token Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/clients/{client_id}/reset-password": { "post": { "tags": [ "superadmin-v2" ], "summary": "Reset Password", "operationId": "reset_password_superadmin_clients__client_id__reset_password_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Client Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/bots": { "get": { "tags": [ "superadmin-v2" ], "summary": "List Bots", "operationId": "list_bots_superadmin_bots_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/bots/{bot_id}": { "get": { "tags": [ "superadmin-v2" ], "summary": "Bot Detail", "operationId": "bot_detail_superadmin_bots__bot_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/documents": { "get": { "tags": [ "superadmin-v2" ], "summary": "List Documents", "operationId": "list_documents_superadmin_documents_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/sessions": { "get": { "tags": [ "superadmin-v2" ], "summary": "List Sessions", "operationId": "list_sessions_superadmin_sessions_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "client_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Client Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/sessions/{session_id}": { "get": { "tags": [ "superadmin-v2" ], "summary": "Session Detail", "operationId": "session_detail_superadmin_sessions__session_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/live/queue": { "get": { "tags": [ "superadmin-v2" ], "summary": "Live Queue", "operationId": "live_queue_superadmin_live_queue_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/leads": { "get": { "tags": [ "superadmin-v2" ], "summary": "List Leads", "operationId": "list_leads_superadmin_leads_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/operators": { "get": { "tags": [ "superadmin-v2" ], "summary": "List Operators", "operationId": "list_operators_superadmin_operators_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/credits/ledger": { "get": { "tags": [ "superadmin-v2" ], "summary": "Credits Ledger", "operationId": "credits_ledger_superadmin_credits_ledger_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "client_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Client Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/pricing-config": { "get": { "tags": [ "superadmin-v2" ], "summary": "List Pricing Config", "operationId": "list_pricing_config_superadmin_pricing_config_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/pricing-config/{key}": { "put": { "tags": [ "superadmin-v2" ], "summary": "Update Pricing Config", "operationId": "update_pricing_config_superadmin_pricing_config__key__put", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "title": "Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlagWrite" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/feature-flags": { "get": { "tags": [ "superadmin-v2" ], "summary": "List Feature Flags", "operationId": "list_feature_flags_superadmin_feature_flags_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/feature-flags/{key}": { "put": { "tags": [ "superadmin-v2" ], "summary": "Update Feature Flag", "operationId": "update_feature_flag_superadmin_feature_flags__key__put", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "title": "Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlagWrite" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/audit": { "get": { "tags": [ "superadmin-v2" ], "summary": "List Audit", "operationId": "list_audit_superadmin_audit_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "actor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor" } }, { "name": "action", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/coupons": { "get": { "tags": [ "superadmin-v2" ], "summary": "List Coupons", "operationId": "list_coupons_superadmin_coupons_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] }, "post": { "tags": [ "superadmin-v2" ], "summary": "Create Coupon", "operationId": "create_coupon_superadmin_coupons_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponCreate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/coupons/{coupon_id}": { "patch": { "tags": [ "superadmin-v2" ], "summary": "Update Coupon", "description": "Partial update of a coupon. Only provided fields are modified.", "operationId": "update_coupon_superadmin_coupons__coupon_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "coupon_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Coupon Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponPatch" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "superadmin-v2" ], "summary": "Delete Coupon", "description": "Delete a coupon.\n\nA coupon that was never redeemed is hard-deleted. Once it has redemptions\nit is instead soft-deactivated (``is_active=False``) so historical\nattribution stays intact \u2014 same reasoning as the plan soft-delete.", "operationId": "delete_coupon_superadmin_coupons__coupon_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "coupon_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Coupon Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/llm/usage": { "get": { "tags": [ "superadmin-v2" ], "summary": "Llm Usage", "operationId": "llm_usage_superadmin_llm_usage_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "model", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/model-config": { "get": { "tags": [ "superadmin-v2" ], "summary": "Get Model Config", "description": "Return the active model + RAG knobs and the catalog of selectable models.", "operationId": "get_model_config_superadmin_model_config_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] }, "put": { "tags": [ "superadmin-v2" ], "summary": "Patch Model Config", "description": "Update LLM models or RAG knobs at runtime.\n\nEach set of changes lands in ``pricing_config`` (the existing super-admin\nkey/value store) and the runtime_config in-memory cache is invalidated so\nnew chat requests see the change within a few seconds.", "operationId": "patch_model_config_superadmin_model_config_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelConfigPatch" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/safety-net-metrics": { "get": { "tags": [ "superadmin-v2" ], "summary": "Safety Net Metrics", "description": "Rolling hourly counts for every safety-net metric (AR-13) \u2014 the\npreviously-missing \"consumer\" for `_safety_net_metric`'s log lines.\nOptionally scoped to a single bot via ``bot_id``.", "operationId": "safety_net_metrics_superadmin_safety_net_metrics_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 168, "minimum": 1, "default": 24, "title": "Hours" } }, { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/email-templates": { "get": { "tags": [ "superadmin-v2" ], "summary": "Email Templates", "description": "Catalog of every Brevo template the platform sends.\n\nPulls the constants from ``email_service`` so this list stays in sync\nautomatically whenever a developer registers a new template ID.", "operationId": "email_templates_superadmin_email_templates_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/logs": { "get": { "tags": [ "superadmin-v2" ], "summary": "Server Logs", "description": "Tail journalctl for the API or worker systemd unit.\n\nSaves the operator from SSH-ing in for routine log checks. The service\nname is allowlisted inside ``logs_service.fetch_logs`` so this endpoint\ncannot be coerced into reading arbitrary units.", "operationId": "server_logs_superadmin_logs_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "service", "in": "query", "required": false, "schema": { "type": "string", "default": "oyechats-api", "title": "Service" } }, { "name": "lines", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "minimum": 10, "default": 500, "title": "Lines" } }, { "name": "level", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Level" } }, { "name": "grep", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Grep" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/observability/langfuse": { "get": { "tags": [ "superadmin-v2" ], "summary": "Langfuse Summary", "description": "Recent Langfuse traces, scores, and daily metrics.\n\nRead-only proxy to the Langfuse public API so the dashboard can show\nLLM activity without re-enabling the SDK on the server (which causes\nAPIConnectionError under memory pressure \u2014 see CLAUDE.md).", "operationId": "langfuse_summary_superadmin_observability_langfuse_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 30, "minimum": 1, "default": 7, "title": "Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/system/health/full": { "get": { "tags": [ "superadmin-v2" ], "summary": "System Health Full", "description": "Detailed health snapshot with per-service connectivity.", "operationId": "system_health_full_superadmin_system_health_full_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/billing/seller-profile": { "get": { "tags": [ "superadmin-v2" ], "summary": "Read Seller Profile", "description": "Seller identity printed on tax invoices (invoicing v2 Phase 0).", "operationId": "read_seller_profile_superadmin_billing_seller_profile_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] }, "put": { "tags": [ "superadmin-v2" ], "summary": "Update Seller Profile", "operationId": "update_seller_profile_superadmin_billing_seller_profile_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerProfileBody" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/invoices": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Invoices", "description": "List invoices (USD-normalised) with optional status / client filters.", "operationId": "list_invoices_superadmin_invoices_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "client_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Client Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/invoices/{invoice_id}": { "get": { "tags": [ "superadmin-v2" ], "summary": "Invoice Detail", "operationId": "invoice_detail_superadmin_invoices__invoice_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Invoice Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/invoices/{invoice_id}/resend-email": { "post": { "tags": [ "superadmin-v2" ], "summary": "Resend Invoice Email", "description": "Re-send the document email to the buyer (e.g. after a lost delivery).", "operationId": "resend_invoice_email_superadmin_invoices__invoice_id__resend_email_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Invoice Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/invoices/{invoice_id}/regenerate-pdf": { "post": { "tags": [ "superadmin-v2" ], "summary": "Regenerate Invoice Pdf", "description": "Queue a fresh PDF render (template fix, corrupted object, \u2026).\n\nClears ``pdf_url`` so the 5-minute worker sweep re-renders and re-uploads\nunder a NEW capability URL; the old R2 object simply becomes unreferenced.\nThe document data itself is immutable \u2014 only the rendering is redone.", "operationId": "regenerate_invoice_pdf_superadmin_invoices__invoice_id__regenerate_pdf_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Invoice Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/billing/gstr-export": { "get": { "tags": [ "superadmin-v2" ], "summary": "Gstr Export Csv", "description": "Document-level GSTR-1-style CSV for the CA (B2B / B2CS / B2CL / EXP /\nCDNR / CDNUR sections + per-section summary). Amounts in RUPEES (two\ndecimals) \u2014 the filing is rupee-denominated, unlike the API's minor units.", "operationId": "gstr_export_csv_superadmin_billing_gstr_export_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "month", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "IST calendar month, e.g. 2026-07", "title": "Month" }, "description": "IST calendar month, e.g. 2026-07" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/billing/reconciliation": { "get": { "tags": [ "superadmin-v2" ], "summary": "Billing Reconciliation", "description": "Anomaly report \u2014 every list should be empty in a healthy system.", "operationId": "billing_reconciliation_superadmin_billing_reconciliation_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/invoices/{invoice_id}/refund": { "post": { "tags": [ "superadmin-ops" ], "summary": "Refund Invoice", "description": "Refund an invoice.\n\nWhen the invoice carries a ``razorpay_payment_id`` a real Razorpay refund\nis issued for the captured amount; the ``refund.created`` webhook then claws\nback the granted credits. Invoices without a gateway reference (manual\ngrants, legacy rows) are marked refunded locally and noted as manual.", "operationId": "refund_invoice_superadmin_invoices__invoice_id__refund_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Invoice Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/invoices/{invoice_id}/mark-paid": { "post": { "tags": [ "superadmin-ops" ], "summary": "Mark Invoice Paid", "description": "Mark an invoice as paid (manual reconciliation).", "operationId": "mark_invoice_paid_superadmin_invoices__invoice_id__mark_paid_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Invoice Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/workers/status": { "get": { "tags": [ "superadmin-ops" ], "summary": "Workers Status", "description": "Best-effort ARQ queue snapshot sourced from Redis.\n\nARQ stores queued jobs in the ``oyechats`` sorted set (the configured\n``queue_name``), in-flight jobs under ``arq:in-progress:*`` and retry-armed\njobs under ``arq:retry:*``. Every metric is best-effort: any Redis hiccup\ndegrades to ``0`` / ``False`` rather than raising, so the dashboard never\nbreaks on a transient blip.", "operationId": "workers_status_superadmin_workers_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/errors": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Errors", "description": "Recent error issues.\n\nThe platform only configures a Sentry **DSN** (write-only ingest key); there\nis no Sentry API auth token / org / project configured, so issues cannot be\nqueried back server-side. Rather than error, this returns an empty list so\nthe dashboard renders an empty state gracefully. Wire up a Sentry API token\nhere to populate it.", "operationId": "list_errors_superadmin_errors_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/webhooks": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Webhook Deliveries", "description": "Recent outbound webhook delivery attempts (newest first).", "operationId": "list_webhook_deliveries_superadmin_webhooks_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/webhooks/{delivery_id}/replay": { "post": { "tags": [ "superadmin-ops" ], "summary": "Replay Webhook Delivery", "description": "Re-deliver a past webhook delivery as a fresh attempt.\n\nRe-enqueues the original event + payload to the same webhook via\n``webhook_service.queue_webhook_delivery`` (ARQ when the worker is enabled,\nin-process thread pool otherwise). The webhook must still exist and be\nactive for the replay to land.", "operationId": "replay_webhook_delivery_superadmin_webhooks__delivery_id__replay_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Delivery Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/documents/{document_id}/reindex": { "post": { "tags": [ "superadmin-ops" ], "summary": "Reindex Document", "description": "Re-run embedding/ingestion for a single document chunk.\n\nEnqueues ``task_reembed_document`` on ARQ when the worker is enabled; when\nit isn't (local dev, worker down) it falls back to re-embedding inline so\nthe action still completes. Either way the document's vector is recomputed\nwith the current embedding provider.", "operationId": "reindex_document_superadmin_documents__document_id__reindex_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/revenue/cohorts": { "get": { "tags": [ "superadmin-ops" ], "summary": "Revenue Cohorts", "description": "Signup-month cohorts with retention and lifetime value.\n\n* ``cohort`` \u2014 signup month (``YYYY-MM``).\n* ``signups`` \u2014 clients whose account was created that month.\n* ``retained`` \u2014 of those, how many still hold an active subscription.\n* ``ltv_cents`` \u2014 total USD-normalised value of *paid* invoices from that\n cohort's clients (cumulative, not per-period).", "operationId": "revenue_cohorts_superadmin_revenue_cohorts_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/stats/timeseries": { "get": { "tags": [ "superadmin-ops" ], "summary": "Stats Timeseries", "description": "Daily time-series for a single platform metric over a trailing window.\n\nReplaces the dashboard's previously-synthetic sparklines with real data.\n\n* ``metric=revenue`` \u2014 paid-invoice value per day, **USD cents** (by paid_at,\n falling back to created_at), normalised via ``_to_usd_cents``.\n* ``metric=messages`` \u2014 chat messages created per day.\n* ``metric=signups`` \u2014 client accounts created per day.\n\nReturns a gap-filled list ``[{date: \"YYYY-MM-DD\", value: int}]`` covering\nevery day in the window (missing days are 0) so charts render continuously.", "operationId": "stats_timeseries_superadmin_stats_timeseries_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "metric", "in": "query", "required": false, "schema": { "type": "string", "default": "revenue", "title": "Metric" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/visitors": { "get": { "tags": [ "superadmin-ops" ], "summary": "Visitor Analytics", "description": "Aggregate behavioral ``VisitorEvent`` data for the analytics dashboard.\n\nCountry / referrer / UTM source are pulled best-effort from the JSONB\n``event_data`` payload (keys ``country``, ``referrer``, ``utm_source``);\nNULL / missing keys are skipped rather than surfaced as empty buckets.\nEvery list is capped at the top 10 and the daily series covers the trailing\n14 days of ``page_view`` events. Empty data degrades to zeros / empty lists.", "operationId": "visitor_analytics_superadmin_visitors_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/funnel": { "get": { "tags": [ "superadmin-ops" ], "summary": "Conversion Funnel", "description": "Compute the visitor \u2192 paying-customer funnel over the trailing window.\n\nEach stage is a single grouped/aggregate query (no per-row Python loops).\n``pct`` is each stage's value as a percentage of the first stage (Sessions),\nrounded to one decimal; it is ``0.0`` when the baseline is ``0``.", "operationId": "conversion_funnel_superadmin_funnel_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/crawls": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Crawls", "description": "List crawl jobs grouped from ``source == \"crawl\"`` document chunks.\n\nA single crawled URL is stored as many ``Document`` rows (one per chunk)\nthat share ``(bot_id, document_name, file_hash)``. We group by ``file_hash``\nto collapse them back into one job per crawl, count the chunks, and take the\nearliest ``created_at`` as the job start. Bot / client names are batch-loaded\nin one query each to avoid N+1 lookups.", "operationId": "list_crawls_superadmin_crawls_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/api-keys": { "get": { "tags": [ "superadmin-ops" ], "summary": "Api Key Registry", "description": "Masked registry of client (``X-API-Key``) and operator keys.\n\nKeys are never returned in full \u2014 only the trailing 4 characters are shown\n(``\u2022\u2022\u2022\u2022\u2022\u20221a2b``); a missing operator key renders as ``\u2014``.", "operationId": "api_key_registry_superadmin_api_keys_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/clients/{client_id}/rotate-api-key": { "post": { "tags": [ "superadmin-ops" ], "summary": "Rotate Client Api Key", "description": "Regenerate a client's ``api_key``, invalidating their current key.\n\nSECURITY: this immediately invalidates the client's existing ``X-API-Key`` \u2014\nany embed / integration using the old key stops authenticating until updated\nwith the new value. The freshly generated key is NOT returned in the response\nbody (only its masked form); retrieve the full value out-of-band if needed.\nThe new key is generated with ``uuid.uuid4().hex`` \u2014 the same generator used\nwhen a client is first created at registration.", "operationId": "rotate_client_api_key_superadmin_clients__client_id__rotate_api_key_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Client Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/offline-messages": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Offline Messages", "description": "Visitor contact-form submissions captured while the team was offline.\n\nNewest first, capped at 500. Filterable by ``status`` (new|read|replied)\nand ``bot_id``. Bot/client names are batch-loaded to avoid N+1.", "operationId": "list_offline_messages_superadmin_offline_messages_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/offline-messages/{message_id}": { "patch": { "tags": [ "superadmin-ops" ], "summary": "Update Offline Message", "description": "Update an offline message's status (new|read|replied), stamping the\nmatching timestamp. Audit-logged.", "operationId": "update_offline_message_superadmin_offline_messages__message_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "message_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Message Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfflineMessagePatch" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/usage-records": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Usage Records", "description": "Per-period usage vs plan limits across clients. Newest period first,\ncapped at 500. Filterable by ``client_id``. Names batch-loaded.", "operationId": "list_usage_records_superadmin_usage_records_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "client_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Client Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/bant-signals": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Bant Signals", "description": "Append-only BANT/MEDDIC qualification signals for auditing extraction\nquality. Newest first, capped at 500. Filter by ``session_id`` and/or\n``dimension`` (budget|authority|need|timeline). Bot/client names are joined\nvia the owning chat session (batch-loaded, no N+1).", "operationId": "list_bant_signals_superadmin_bant_signals_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "session_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" } }, { "name": "dimension", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dimension" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/webhook-registrations": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Webhook Registrations", "description": "All customer-registered outbound webhooks (distinct from the delivery\nlog). The signing secret is never returned. Newest first, capped at 500,\nfilterable by ``bot_id``. Bot/client names batch-loaded.", "operationId": "list_webhook_registrations_superadmin_webhook_registrations_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/webhook-registrations/{webhook_id}": { "patch": { "tags": [ "superadmin-ops" ], "summary": "Update Webhook Registration", "description": "Enable or disable a customer webhook registration. Audit-logged.", "operationId": "update_webhook_registration_superadmin_webhook_registrations__webhook_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Webhook Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRegistrationPatch" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/webhook-registrations/{webhook_id}/test": { "post": { "tags": [ "superadmin-ops" ], "summary": "Test Webhook Registration", "description": "Dispatch a sample ``tier_transition`` event to a registration so the\nsuperadmin can verify the customer endpoint is reachable. Audit-logged.", "operationId": "test_webhook_registration_superadmin_webhook_registrations__webhook_id__test_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Webhook Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/payment-methods": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Payment Methods", "description": "Stored payment methods across clients (card / UPI / bank).\n\nNewest first, capped at 500, filterable by ``client_id``. Provider token\nreferences (``razorpay_token_id``) are never\nreturned \u2014 only the non-sensitive display fields. Client names batch-loaded.", "operationId": "list_payment_methods_superadmin_payment_methods_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "client_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Client Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/meeting-bookings": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Meeting Bookings", "description": "Meeting bookings captured during chat sessions.\n\nNewest first, capped at 500, filterable by ``bot_id``. Bot/client names\nare batch-loaded (Bot \u2192 client_id \u2192 Client) to avoid N+1 lookups.", "operationId": "list_meeting_bookings_superadmin_meeting_bookings_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/oauth-accounts": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Oauth Accounts", "description": "Linked external identity provider accounts (Google, etc.).\n\nNewest first, capped at 500, filterable by ``client_id``. Only the\nprovider-reported, non-secret fields are returned. Client names batch-loaded.", "operationId": "list_oauth_accounts_superadmin_oauth_accounts_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "client_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Client Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/oauth-accounts/{account_id}": { "delete": { "tags": [ "superadmin-ops" ], "summary": "Unlink Oauth Account", "description": "Unlink an external identity provider account from its client. Audit-logged.", "operationId": "unlink_oauth_account_superadmin_oauth_accounts__account_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Account Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/failed-webhooks": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Failed Webhooks", "description": "Dead-lettered billing webhooks whose processing failed.\n\nNewest first, capped at 500, filterable by ``status`` (pending|replayed|\nignored). The raw signed payload, signature, and captured headers are never\nreturned \u2014 only the non-sensitive metadata needed to triage and replay.", "operationId": "list_failed_webhooks_superadmin_failed_webhooks_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/failed-webhooks/{failed_webhook_id}/replay": { "post": { "tags": [ "superadmin-ops" ], "summary": "Replay Failed Webhook", "description": "Re-verify and reprocess a dead-lettered Razorpay billing webhook.\n\nMirrors the inbound ``/webhooks/razorpay`` handler: the stored raw signed\nbytes are re-verified against ``RAZORPAY_WEBHOOK_SECRET`` (signature mismatch\n\u2192 400), parsed, and dispatched to ``razorpay_service.handle_webhook_event``.\nIdempotency on the provider event id makes a successful replay safe even if\nthe original eventually processed. On success the row is marked ``replayed``;\non a handler error the row is left untouched and a 502 is returned.", "operationId": "replay_failed_webhook_superadmin_failed_webhooks__failed_webhook_id__replay_post", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "failed_webhook_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Failed Webhook Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/referral-conversions": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Referral Conversions", "description": "Snapshots of commission/discount terms at the moment a referral converted.\n\nNewest first, capped at 500, filterable by ``affiliate_id``. ``*_pct`` are\nthe basis-point columns expressed as percentages (bps / 100). The referral\ncode, customer client name, and affiliate's own client name are batch-loaded\nto avoid N+1 lookups.", "operationId": "list_referral_conversions_superadmin_referral_conversions_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "affiliate_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Affiliate Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/notifications": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Notifications", "description": "In-app dashboard notifications across workspaces.\n\nNewest first, capped at 500, filterable by ``type``.", "operationId": "list_notifications_superadmin_notifications_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/push-subscriptions": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Push Subscriptions", "description": "Web Push device subscriptions for operators / workspace owners.\n\nNewest first, capped at 500. The endpoint is masked to its host (the path\ncarries a per-device secret); ``p256dh`` and ``auth`` keys are never returned.", "operationId": "list_push_subscriptions_superadmin_push_subscriptions_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/processed-webhooks": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Processed Webhooks", "description": "Inbound provider webhook idempotency log (event ids already processed).\n\nNewest first by ``processed_at``, capped at 500, filterable by ``provider``.", "operationId": "list_processed_webhooks_superadmin_processed_webhooks_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "provider", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/bot-growth-events": { "get": { "tags": [ "superadmin-ops" ], "summary": "List Bot Growth Events", "description": "Per-bot growth events (demo-link distribution telemetry).\n\nNewest first, capped at 500, filterable by ``bot_id``. Bot names batch-loaded.", "operationId": "list_bot_growth_events_superadmin_bot_growth_events_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "bot_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/llm/cost-breakdown": { "get": { "tags": [ "superadmin-ops" ], "summary": "Llm Cost Breakdown", "description": "Aggregate LLM call metering over a trailing window, grouped by model or client.\n\nEach row totals calls, prompt/completion tokens, cost (USD cents), and the\nnumber of errored calls, ordered by ``cost_cents`` descending. For\n``by=model`` the key and label are the model name; for ``by=client`` the key\nis the stringified client id and the label is the client name (NULL client \u2192\n``\"\u2014\"``). Client names are batch-loaded to avoid N+1.", "operationId": "llm_cost_breakdown_superadmin_llm_cost_breakdown_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 1, "default": 30, "title": "Days" } }, { "name": "by", "in": "query", "required": false, "schema": { "type": "string", "default": "model", "title": "By" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/webhooks/razorpay": { "post": { "tags": [ "billing-webhooks" ], "summary": "Razorpay Webhook", "description": "Handle Razorpay webhook events.\n\nVerifies the ``X-Razorpay-Signature`` HMAC against the raw request body\nusing ``RAZORPAY_WEBHOOK_SECRET``, then delegates dispatch to\n:func:`razorpay_service.handle_webhook_event`. Idempotency is keyed on\nthe ``X-Razorpay-Event-Id`` header (present on all modern deliveries).\n\nOn a processing failure the raw signed event is dead-lettered (so it can\nbe replayed) and, when ``WEBHOOK_RETRY_ON_ERROR`` is on (default), the\nroute returns 5xx so Razorpay retries \u2014 safe because event-id idempotency\nmakes the eventual successful retry a no-op. The flag can be turned off to\nfall back to the legacy 200-on-error behaviour, but the event is still\ndead-lettered either way.", "operationId": "razorpay_webhook_webhooks_razorpay_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/affiliates/validate": { "get": { "tags": [ "affiliate" ], "summary": "Validate Code", "description": "Check whether ``code`` is a valid + active referral code.\n\nAggressively rate-limited (60/min/IP) so the endpoint cannot be used\nto enumerate the code namespace. Always returns 200 with\n``{valid: bool}`` \u2014 using HTTP status to leak validity would defeat\nthe rate-limit defense.", "operationId": "validate_code_affiliates_validate_get", "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string", "title": "Code" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateCodeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/affiliates/click": { "post": { "tags": [ "affiliate" ], "summary": "Record Click", "description": "Record a click on a referral link.\n\nFire-and-forget from the client perspective \u2014 we always return 204,\neven for invalid codes, so the caller cannot time-attack to enumerate\nvalid codes. The body's IP and User-Agent are extracted from the\nrequest headers (not the body) so callers cannot spoof them.", "operationId": "record_click_affiliates_click_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClickRequest" } } }, "required": true }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/affiliate/referral-status": { "get": { "tags": [ "affiliate" ], "summary": "Referral Status", "description": "Return the account's standing referral attribution, if any.\n\nThe checkout modal calls this on open so an already-attributed account\nshows its permanent discount badge instead of an editable code field \u2014\nattribution is first-touch and cannot be removed, and the server applies\nthe discount at checkout regardless of what the UI shows.", "operationId": "referral_status_affiliate_referral_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralStatusResponse" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/affiliate/apply-referral": { "post": { "tags": [ "affiliate" ], "summary": "Apply Referral", "description": "Apply a referral code for the currently-authenticated customer.\n\nCalled from the checkout modal when the user enters a referral code before\nbuying a plan or top-up. Delegates to ``attribute_signup`` which enforces\nfirst-touch wins and self-referral prevention \u2014 idempotent, never blocks.\n\nReturns ``{ attributed, code, discount_pct }``:\n * ``attributed=true`` \u2014 freshly attributed on this call.\n * ``attributed=false`` with non-null ``code`` and ``discount_pct`` \u2014 the\n account was already attributed to this same code; UX should still\n show the discount applied (idempotent re-entry by the same user).\n * ``attributed=false`` with ``code=None`` \u2014 invalid code OR account\n is already attributed to a *different* code (collision).\nAlways returns 200 so checkout is never blocked.", "operationId": "apply_referral_affiliate_apply_referral_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyReferralRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyReferralResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/affiliate/me": { "get": { "tags": [ "affiliate" ], "summary": "Get Me", "operationId": "get_me_affiliate_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/affiliate/codes": { "get": { "tags": [ "affiliate" ], "summary": "List My Codes", "operationId": "list_my_codes_affiliate_codes_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CodeRow" }, "type": "array", "title": "Response List My Codes Affiliate Codes Get" } } } } }, "security": [ { "APIKeyHeader": [] } ] }, "post": { "tags": [ "affiliate" ], "summary": "Create My Code", "operationId": "create_my_code_affiliate_codes_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCodeRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeRow" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/affiliate/codes/{code_id}/referrals": { "get": { "tags": [ "affiliate" ], "summary": "List My Code Referrals", "description": "List the customers who signed up via one of this affiliate's codes.\n\nAuthorisation: the code must belong to the calling affiliate. We return\n404 (not 403) when the code exists but is owned by someone else so an\naffiliate can't probe the global code namespace.", "operationId": "list_my_code_referrals_affiliate_codes__code_id__referrals_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "code_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Code Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeReferralsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/affiliate/codes/{code_id}": { "patch": { "tags": [ "affiliate" ], "summary": "Update My Code", "operationId": "update_my_code_affiliate_codes__code_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "code_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Code Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCodeRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeRow" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/affiliate/stats": { "get": { "tags": [ "affiliate" ], "summary": "Get My Stats", "operationId": "get_my_stats_affiliate_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AffiliateStats" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/affiliate-invites/lookup": { "get": { "tags": [ "affiliate" ], "summary": "Lookup Invite", "description": "Resolve a magic-link token to its target email + expiry.\n\nCalled by the ``/affiliate-invite`` landing page before deciding which\nbranch to render \u2014 the recipient sees their invited email + expiry\ndeadline, and (when logged in) the page auto-fires accept-existing.\nRate-limited to slow token enumeration. Returns 404/410 for invalid /\nused / expired tokens.", "operationId": "lookup_invite_affiliate_invites_lookup_get", "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "title": "Token" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInviteLookupResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/affiliate-invites/accept": { "post": { "tags": [ "affiliate" ], "summary": "Accept Invite", "description": "Accept a magic-link invite \u2014 atomically create Client + Affiliate.\n\nRate-limited (10/min/IP) on top of the token's natural one-shot\nconstraint. On success, returns the same shape as /auth/register so\nthe admin app can store the api_key and route the user straight to\n/affiliate without a separate login round-trip.", "operationId": "accept_invite_affiliate_invites_accept_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInviteRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInviteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/affiliate-invites/accept-existing": { "post": { "tags": [ "affiliate" ], "summary": "Accept Invite Existing", "description": "Accept an invite while already signed in as an OyeChats client.\n\nThe other accept endpoint creates a brand-new Client+Affiliate pair \u2014\nthis one wires an Affiliate row to the client who's already\nauthenticated. Used by the unified `/affiliate-invite` landing page\nwhen the recipient already has an account.\n\nStatus codes:\n * 200 \u2014 affiliate row created, fire the welcome email\n * 403 \u2014 token's email doesn't match the logged-in client\n * 404 \u2014 token doesn't exist\n * 409 \u2014 client is already an active affiliate\n * 410 \u2014 token expired or already used", "operationId": "accept_invite_existing_affiliate_invites_accept_existing_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInviteForExistingRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInviteForExistingResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/affiliates": { "get": { "tags": [ "affiliate", "superadmin" ], "summary": "List All Affiliates", "operationId": "list_all_affiliates_superadmin_affiliates_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AffiliateRow" }, "type": "array", "title": "Response List All Affiliates Superadmin Affiliates Get" } } } } }, "security": [ { "APIKeyHeader": [] } ] }, "post": { "tags": [ "affiliate", "superadmin" ], "summary": "Invite", "description": "Invite anyone to the affiliate program \u2014 existing customer or stranger.\n\nTwo paths, selected automatically by the service:\n\n* **Existing customer**: creates the ``Affiliate`` row immediately and\n fires a welcome email pointing at ``/affiliate``. Response\n ``kind == \"instant\"``.\n* **Stranger**: creates an ``AffiliateInvite`` row + raw token, and\n fires a magic-link email pointing at ``/affiliate-invite?token=...``.\n Response ``kind == \"pending_invite\"``. The raw token is never\n returned to the caller (super admin) \u2014 only embedded in the email,\n so a compromised admin session can't replay invites.\n\nThe 5-seat cap is enforced at invite time AND again at accept time \u2014\na long-running pending invite can't sneak past the cap.", "operationId": "invite_superadmin_affiliates_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteAffiliateRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/affiliates/invites": { "get": { "tags": [ "affiliate", "superadmin" ], "summary": "List Invites", "description": "List pending (un-accepted, un-revoked, un-expired) magic-link invites.", "operationId": "list_invites_superadmin_affiliates_invites_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PendingInviteRow" }, "type": "array", "title": "Response List Invites Superadmin Affiliates Invites Get" } } } } }, "security": [ { "APIKeyHeader": [] } ] } }, "/superadmin/affiliates/invites/{invite_id}": { "delete": { "tags": [ "affiliate", "superadmin" ], "summary": "Revoke", "description": "Revoke a pending invite \u2014 its token can no longer be used to onboard.", "operationId": "revoke_superadmin_affiliates_invites__invite_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "invite_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Invite Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/affiliates/{affiliate_id}": { "get": { "tags": [ "affiliate", "superadmin" ], "summary": "Get Affiliate Detail", "description": "Detail bundle: affiliate meta + their codes + aggregate stats.", "operationId": "get_affiliate_detail_superadmin_affiliates__affiliate_id__get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "affiliate_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Affiliate Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "affiliate", "superadmin" ], "summary": "Update Affiliate Route", "description": "Override caps or toggle the affiliate's active status.", "operationId": "update_affiliate_route_superadmin_affiliates__affiliate_id__patch", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "affiliate_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Affiliate Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAffiliateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AffiliateRow" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "affiliate", "superadmin" ], "summary": "Delete Affiliate Route", "description": "Hard-delete an affiliate, all their codes, and the click history.\n\nReferred clients survive \u2014 their ``referral_code_id`` becomes NULL via\nthe FK's ``ON DELETE SET NULL``. Historical attribution is irreversibly\nlost from those client rows. This is a destructive operation by design\n\u2014 the super-admin UI requires an explicit two-step confirm before it\nfires.", "operationId": "delete_affiliate_route_superadmin_affiliates__affiliate_id__delete", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "affiliate_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Affiliate Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/superadmin/affiliates/{affiliate_id}/codes/{code_id}/referrals": { "get": { "tags": [ "affiliate", "superadmin" ], "summary": "List Code Referrals Super", "description": "Same shape as the affiliate-scoped route, but with PII unmasked and\nthe platform commission slice populated. Auth gate is the router-level\n``get_superadmin`` dependency.\n\nReturns 404 when ``code_id`` doesn't exist OR isn't owned by\n``affiliate_id`` \u2014 the latter is a 404 (not 403) so the global code\nnamespace isn't probeable by URL-walking.", "operationId": "list_code_referrals_super_superadmin_affiliates__affiliate_id__codes__code_id__referrals_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "affiliate_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Affiliate Id" } }, { "name": "code_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Code Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeReferralsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/health": { "get": { "tags": [ "system" ], "summary": "Health Check", "description": "Readiness check for user-facing traffic.\n\nReturns **200** when the API can serve user requests (DB + Redis\nreachable). Returns **503** only when one of those is down. Worker\nstatus is reported in the body for ops visibility but does **not**\ngate the response code: a degraded worker means BANT extraction and\nasync email pause, while chats themselves still work \u2014 failing the\ndeploy gate or load-balancer probe in that case would cause\nuser-visible downtime that wasn't there.\n\nUsed by deploy scripts, Nginx upstream checks, and external uptime\nmonitors. For comprehensive checks (worker included), use\n``/health/full``.", "operationId": "health_check_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/health/full": { "get": { "tags": [ "system" ], "summary": "Health Check Full", "description": "Comprehensive health check including the worker.\n\nReturns **200** only when DB + Redis + worker are all green. Returns\n**503** if any subsystem is degraded \u2014 including a missing worker\nheartbeat. Use this for alerting that should page on partial\ndegradation; use ``/health`` for deploy gates and load-balancer\nprobes that must not flap on transient worker hiccups.", "operationId": "health_check_full_health_full_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/health/live": { "get": { "tags": [ "system" ], "summary": "Liveness Probe", "description": "Ultra-lightweight liveness probe. No DB/Redis calls.\n\nReturns 200 if the process is alive. Used by external uptime monitors\n(BetterStack, UptimeRobot) where low-latency checks are preferred.", "operationId": "liveness_probe_health_live_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/": { "get": { "summary": "Read Root", "operationId": "read_root__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/files/{file_path}": { "get": { "summary": "Serve B2 File", "description": "Serve a file from private B2 by proxying the content.", "operationId": "serve_b2_file_files__file_path__get", "parameters": [ { "name": "file_path", "in": "path", "required": true, "schema": { "type": "string", "title": "File Path" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "AcceptChatRequest": { "properties": { "operator_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Operator Id" } }, "type": "object", "title": "AcceptChatRequest" }, "AcceptInviteForExistingRequest": { "properties": { "token": { "type": "string", "title": "Token" } }, "type": "object", "required": [ "token" ], "title": "AcceptInviteForExistingRequest" }, "AcceptInviteForExistingResponse": { "properties": { "is_affiliate": { "type": "boolean", "title": "Is Affiliate", "default": true }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "message" ], "title": "AcceptInviteForExistingResponse" }, "AcceptInviteLookupResponse": { "properties": { "email": { "type": "string", "title": "Email" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" } }, "type": "object", "required": [ "email", "expires_at" ], "title": "AcceptInviteLookupResponse" }, "AcceptInviteRequest": { "properties": { "token": { "type": "string", "title": "Token" }, "name": { "type": "string", "title": "Name" }, "password": { "type": "string", "title": "Password" }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Name" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" } }, "type": "object", "required": [ "token", "name", "password" ], "title": "AcceptInviteRequest" }, "AcceptInviteResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token" }, "token_type": { "type": "string", "title": "Token Type", "default": "bearer" }, "client_id": { "type": "integer", "title": "Client Id" }, "name": { "type": "string", "title": "Name" }, "is_affiliate": { "type": "boolean", "title": "Is Affiliate", "default": true } }, "type": "object", "required": [ "access_token", "client_id", "name" ], "title": "AcceptInviteResponse" }, "AffiliateRow": { "properties": { "id": { "type": "integer", "title": "Id" }, "client_id": { "type": "integer", "title": "Client Id" }, "client_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Email" }, "client_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Name" }, "max_active_codes": { "type": "integer", "title": "Max Active Codes" }, "commission_pct": { "type": "number", "title": "Commission Pct" }, "commission_bps": { "type": "integer", "title": "Commission Bps" }, "invited_by": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Invited By" }, "active": { "type": "boolean", "title": "Active" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "deactivated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deactivated At" }, "total_clicks": { "type": "integer", "title": "Total Clicks" }, "total_signups": { "type": "integer", "title": "Total Signups" }, "active_codes": { "type": "integer", "title": "Active Codes" }, "conversion_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Conversion Pct" } }, "type": "object", "required": [ "id", "client_id", "client_email", "client_name", "max_active_codes", "commission_pct", "commission_bps", "invited_by", "active", "created_at", "deactivated_at", "total_clicks", "total_signups", "active_codes", "conversion_pct" ], "title": "AffiliateRow" }, "AffiliateStats": { "properties": { "total_clicks": { "type": "integer", "title": "Total Clicks" }, "total_signups": { "type": "integer", "title": "Total Signups" }, "active_codes": { "type": "integer", "title": "Active Codes" }, "max_active_codes": { "type": "integer", "title": "Max Active Codes" }, "conversion_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Conversion Pct" } }, "type": "object", "required": [ "total_clicks", "total_signups", "active_codes", "max_active_codes", "conversion_pct" ], "title": "AffiliateStats" }, "ApplyReferralRequest": { "properties": { "code": { "type": "string", "maxLength": 20, "minLength": 3, "title": "Code" } }, "type": "object", "required": [ "code" ], "title": "ApplyReferralRequest" }, "ApplyReferralResponse": { "properties": { "attributed": { "type": "boolean", "title": "Attributed" }, "message": { "type": "string", "title": "Message" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code" }, "discount_pct": { "type": "number", "title": "Discount Pct", "default": 0.0 } }, "type": "object", "required": [ "attributed", "message" ], "title": "ApplyReferralResponse" }, "BehavioralSignalsRequest": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "page_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Url" }, "referrer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Referrer" }, "utm_params": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Utm Params" }, "time_on_page": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Time On Page" }, "pages_viewed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pages Viewed" }, "is_return_visit": { "type": "boolean", "title": "Is Return Visit", "default": false }, "journey": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Journey" } }, "type": "object", "required": [ "session_id" ], "title": "BehavioralSignalsRequest" }, "BillingDetailsBody": { "properties": { "legal_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legal Name" }, "gstin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gstin" }, "billing_address": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Billing Address" }, "billing_country": { "anyOf": [ { "type": "string", "maxLength": 2 }, { "type": "null" } ], "title": "Billing Country" }, "billing_state_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Billing State Code" }, "billing_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Billing Email" } }, "type": "object", "title": "BillingDetailsBody" }, "Body_ingest_documents_ingest_post": { "properties": { "files": { "items": { "type": "string", "contentMediaType": "application/octet-stream" }, "type": "array", "title": "Files" } }, "type": "object", "required": [ "files" ], "title": "Body_ingest_documents_ingest_post" }, "Body_upload_chat_file_route_operators_upload_chat_file_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_chat_file_route_operators_upload_chat_file_post" }, "Body_upload_feedback_attachment_client_feedback_upload_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_feedback_attachment_client_feedback_upload_post" }, "Body_upload_logo_endpoint_client_upload_logo_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_logo_endpoint_client_upload_logo_post" }, "BotCheckoutRequest": { "properties": { "name": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Name" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" }, "plan_slug": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Plan Slug" }, "billing_cycle": { "type": "string", "pattern": "^(monthly|annual)$", "title": "Billing Cycle", "default": "monthly" }, "allowed_domains": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Domains" }, "domain_check_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Domain Check Enabled" } }, "type": "object", "required": [ "name", "plan_slug" ], "title": "BotCheckoutRequest", "description": "Body for ``POST /bots/checkout`` \u2014 start a per-bot subscription.\n\nThe bot row is NOT created here. We pass the bot's name + website +\ndomain settings in the Razorpay subscription notes so the activation\nwebhook (or the sync verify endpoint) can materialise the bot only\nafter payment captures. Dismissed checkouts leave no orphan rows." }, "BotCheckoutVerifyRequest": { "properties": { "razorpay_payment_id": { "type": "string", "title": "Razorpay Payment Id" }, "razorpay_subscription_id": { "type": "string", "title": "Razorpay Subscription Id" }, "razorpay_signature": { "type": "string", "title": "Razorpay Signature" } }, "type": "object", "required": [ "razorpay_payment_id", "razorpay_subscription_id", "razorpay_signature" ], "title": "BotCheckoutVerifyRequest", "description": "Body for ``POST /bots/checkout/verify`` \u2014 sync fallback for localhost.\n\nWebhook delivery is the source of truth in production, but Razorpay\ncan't hit ``localhost`` so the success callback hits this endpoint to\ntrigger the activation handler synchronously. Idempotent: re-running\non an already-active subscription is a no-op (the handler short-\ncircuits when the local row already exists)." }, "BotResponse": { "properties": { "id": { "type": "integer", "title": "Id" }, "bot_key": { "type": "string", "title": "Bot Key" }, "name": { "type": "string", "title": "Name" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Prompt" }, "brand_tone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Brand Tone" }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Name" }, "company_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Description" }, "bot_logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bot Logo" }, "launcher_name": { "type": "string", "title": "Launcher Name" }, "launcher_logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Launcher Logo" }, "primary_color": { "type": "string", "title": "Primary Color" }, "background_color": { "type": "string", "title": "Background Color" }, "header_color": { "type": "string", "title": "Header Color" }, "recommended_colors": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Recommended Colors" }, "user_bubble_color": { "type": "string", "title": "User Bubble Color", "default": "#DBE9FF" }, "bant_enabled": { "type": "boolean", "title": "Bant Enabled" }, "bant_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Bant Config" }, "relevance_threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Relevance Threshold" }, "avatar_type": { "type": "string", "title": "Avatar Type" }, "orb_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Orb Color" }, "lead_form_enabled": { "type": "boolean", "title": "Lead Form Enabled", "default": false }, "lead_form_fields": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Lead Form Fields" }, "notification_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notification Email" }, "notification_emails": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Notification Emails" }, "reply_to_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reply To Email" }, "email_on_qualified": { "type": "boolean", "title": "Email On Qualified", "default": true }, "email_on_handoff": { "type": "boolean", "title": "Email On Handoff", "default": true }, "email_on_offline": { "type": "boolean", "title": "Email On Offline", "default": true }, "email_visitor_confirmation": { "type": "boolean", "title": "Email Visitor Confirmation", "default": true }, "live_chat_enabled": { "type": "boolean", "title": "Live Chat Enabled", "default": true }, "operator_timeout_seconds": { "type": "integer", "title": "Operator Timeout Seconds", "default": 120 }, "live_chat_queue_timeout_seconds": { "type": "integer", "title": "Live Chat Queue Timeout Seconds", "default": 20 }, "live_chat_max_queue_size": { "type": "integer", "title": "Live Chat Max Queue Size", "default": 10 }, "business_hours": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Business Hours" }, "feature_flags": { "additionalProperties": true, "type": "object", "title": "Feature Flags", "default": {} }, "widget_messages": { "additionalProperties": true, "type": "object", "title": "Widget Messages", "default": {} }, "widget_config": { "additionalProperties": true, "type": "object", "title": "Widget Config", "default": {} }, "branding_text": { "type": "string", "title": "Branding Text", "default": "Powered by OyeChats" }, "branding_url": { "type": "string", "title": "Branding Url", "default": "https://oyechats.com" }, "welcome_title": { "type": "string", "title": "Welcome Title", "default": "Hi there \ud83d\udc4b" }, "welcome_subtitle": { "type": "string", "title": "Welcome Subtitle", "default": "How can we help you today?" }, "waiting_message": { "type": "string", "title": "Waiting Message", "default": "Connecting you to support..." }, "offline_message": { "type": "string", "title": "Offline Message", "default": "We'll be right back! Leave a message and we'll follow up shortly." }, "handoff_delay_seconds": { "type": "integer", "title": "Handoff Delay Seconds", "default": 0 }, "calendly_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Calendly Url" }, "meeting_booking_enabled": { "type": "boolean", "title": "Meeting Booking Enabled", "default": false }, "meeting_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Meeting Provider" }, "zcal_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Zcal Url" }, "calcom_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Calcom Url" }, "services": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Services" }, "services_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Services Url" }, "allowed_domains": { "items": { "type": "string" }, "type": "array", "title": "Allowed Domains", "default": [] }, "domain_check_enabled": { "type": "boolean", "title": "Domain Check Enabled", "default": false }, "is_active": { "type": "boolean", "title": "Is Active" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "id", "bot_key", "name", "website", "system_prompt", "bot_logo", "launcher_name", "launcher_logo", "primary_color", "background_color", "header_color", "recommended_colors", "bant_enabled", "avatar_type", "orb_color", "is_active", "created_at" ], "title": "BotResponse" }, "CancelSubscriptionRequest": { "properties": { "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "bot_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } }, "type": "object", "title": "CancelSubscriptionRequest" }, "ChangeEmailConfirm": { "properties": { "otp": { "type": "string", "title": "Otp" } }, "type": "object", "required": [ "otp" ], "title": "ChangeEmailConfirm" }, "ChangeEmailRequest": { "properties": { "new_email": { "type": "string", "title": "New Email" }, "current_password": { "type": "string", "title": "Current Password" } }, "type": "object", "required": [ "new_email", "current_password" ], "title": "ChangeEmailRequest" }, "ChangePasswordRequest": { "properties": { "current_password": { "type": "string", "title": "Current Password" }, "new_password": { "type": "string", "title": "New Password" } }, "type": "object", "required": [ "current_password", "new_password" ], "title": "ChangePasswordRequest" }, "ChangePlanRequest": { "properties": { "plan_id": { "type": "integer", "title": "Plan Id" }, "billing_cycle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Billing Cycle" } }, "type": "object", "required": [ "plan_id" ], "title": "ChangePlanRequest" }, "ChatRequest": { "properties": { "question": { "type": "string", "maxLength": 5000, "minLength": 1, "title": "Question" }, "session_id": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Session Id" }, "cta_dimension": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Cta Dimension" } }, "type": "object", "required": [ "question" ], "title": "ChatRequest" }, "CheckoutRequest": { "properties": { "plan_id": { "type": "integer", "title": "Plan Id" }, "billing_cycle": { "type": "string", "title": "Billing Cycle", "default": "monthly" }, "coupon_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Coupon Code" }, "billing_country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Billing Country" } }, "type": "object", "required": [ "plan_id" ], "title": "CheckoutRequest" }, "ClickRequest": { "properties": { "code": { "type": "string", "title": "Code" }, "referrer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Referrer" } }, "type": "object", "required": [ "code" ], "title": "ClickRequest" }, "ClientPatch": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "is_superadmin": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Superadmin" }, "superadmin_role": { "anyOf": [ { "type": "string", "pattern": "^(owner|admin|readonly)$" }, { "type": "null" } ], "title": "Superadmin Role" }, "suspended": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Suspended" } }, "type": "object", "title": "ClientPatch" }, "ClientProfilePatch": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" } }, "type": "object", "title": "ClientProfilePatch" }, "ClientSettingsUpdate": { "properties": { "bot_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bot Name" }, "bot_logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bot Logo" }, "launcher_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Launcher Name" }, "launcher_logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Launcher Logo" }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Color" }, "background_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Background Color" }, "header_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Header Color" } }, "type": "object", "title": "ClientSettingsUpdate" }, "CodeReferralsResponse": { "properties": { "code": { "type": "string", "title": "Code" }, "breakdown": { "$ref": "#/components/schemas/CommissionBreakdown" }, "distribution": { "$ref": "#/components/schemas/PricingDistribution" }, "referrals": { "items": { "$ref": "#/components/schemas/ReferralRow" }, "type": "array", "title": "Referrals" } }, "type": "object", "required": [ "code", "breakdown", "distribution", "referrals" ], "title": "CodeReferralsResponse" }, "CodeRow": { "properties": { "id": { "type": "integer", "title": "Id" }, "code": { "type": "string", "title": "Code" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "active": { "type": "boolean", "title": "Active" }, "affiliate_commission_pct": { "type": "number", "title": "Affiliate Commission Pct" }, "customer_discount_pct": { "type": "number", "title": "Customer Discount Pct" }, "affiliate_commission_bps": { "type": "integer", "title": "Affiliate Commission Bps" }, "customer_discount_bps": { "type": "integer", "title": "Customer Discount Bps" }, "clicks": { "type": "integer", "title": "Clicks" }, "signups": { "type": "integer", "title": "Signups" }, "conversion_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Conversion Pct" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "deactivated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Deactivated At" } }, "type": "object", "required": [ "id", "code", "label", "active", "affiliate_commission_pct", "customer_discount_pct", "affiliate_commission_bps", "customer_discount_bps", "clicks", "signups", "conversion_pct", "created_at", "deactivated_at" ], "title": "CodeRow" }, "CommissionBreakdown": { "properties": { "pool_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Pool Pct" }, "affiliate_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Affiliate Pct" }, "customer_discount_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Customer Discount Pct" }, "code_unused_pool_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Code Unused Pool Pct" }, "platform_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Platform Pct" } }, "type": "object", "required": [ "pool_pct", "affiliate_pct", "customer_discount_pct", "code_unused_pool_pct" ], "title": "CommissionBreakdown" }, "ConnectRequestResponseBody": { "properties": { "accepted": { "type": "boolean", "title": "Accepted" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" } }, "type": "object", "required": [ "accepted" ], "title": "ConnectRequestResponseBody" }, "CouponCreate": { "properties": { "code": { "type": "string", "title": "Code" }, "percent_off": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Percent Off" }, "amount_off_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Amount Off Cents" }, "max_redemptions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Redemptions" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "applies_to_plan_ids": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Applies To Plan Ids" } }, "type": "object", "required": [ "code" ], "title": "CouponCreate" }, "CouponPatch": { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code" }, "percent_off": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Percent Off" }, "amount_off_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Amount Off Cents" }, "max_redemptions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Redemptions" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "applies_to_plan_ids": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Applies To Plan Ids" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" } }, "type": "object", "title": "CouponPatch" }, "CrawlDiffRequest": { "properties": { "url": { "type": "string", "title": "Url" }, "replace_source": { "type": "string", "minLength": 1, "title": "Replace Source", "description": "Root domain whose existing pages should be diffed against the live sitemap (e.g. 'oyechats.com')." }, "mode": { "type": "string", "title": "Mode", "description": "Recrawl preview mode. ``full`` shows the totals for a re-scrape of every URL (charged per page regardless of content change). ``delta`` shows the URL-level diff and defers content-change detection to the ingestion pipeline's SHA-256 dedup \u2014 only new or changed pages are billed. ``delta`` is gated to Standard+; Free/Starter callers get 403.", "default": "delta" } }, "type": "object", "required": [ "url", "replace_source" ], "title": "CrawlDiffRequest", "description": "Request body for POST /crawl/diff \u2014 diff a recrawl against existing pages." }, "CrawlDiscoverRequest": { "properties": { "url": { "type": "string", "title": "Url" } }, "type": "object", "required": [ "url" ], "title": "CrawlDiscoverRequest", "description": "Request body for POST /crawl/discover \u2014 URL-only pre-crawl page count." }, "CrawlRequest": { "properties": { "url": { "type": "string", "title": "Url" }, "max_pages": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Max Pages" }, "use_js": { "type": "boolean", "title": "Use Js", "description": "Enable JavaScript (browser) mode for all pages. Required for Next.js, React, and other SPA sites.", "default": false }, "replace_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Replace Source", "description": "Root domain to atomically replace after a successful crawl (e.g. 'fynix.digital'). Old chunks for this source are deleted only after new ingestion succeeds \u2014 so the bot always has knowledge during the recrawl." }, "expected_new_pages": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Expected New Pages", "description": "Optional client-supplied page count from a prior /crawl/diff call, used to right-size the credit pre-flight on a recrawl (only honored when ``replace_source`` is set). Per-page atomic deduction inside the ingestion pipeline remains authoritative \u2014 this only loosens the upfront ceiling so a 9-new-page recrawl isn't blocked by a 1200-page worst-case reservation." }, "ordered_urls": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Ordered Urls", "description": "Explicit, pre-ordered list of URLs to crawl (from a prior /crawl/discover, sorted client-side by the user's chosen order and truncated to the affordable count). When set, the recursive crawl is skipped and exactly these URLs are fetched in order. Validated same-origin and capped server-side." }, "mode": { "type": "string", "title": "Mode", "description": "Recrawl mode. ``full`` forces re-embed + charge for every discovered URL (Free/Starter's only option) \u2014 the ingestion pipeline's SHA-256 dedup is bypassed so unchanged pages still bill. ``delta`` uses the existing dedup so only new or content-changed pages bill. ``delta`` is gated to Standard+; Free/Starter callers get 403. First-time crawls (no ``replace_source``) always run as full \u2014 the mode field is ignored.", "default": "delta" } }, "type": "object", "required": [ "url" ], "title": "CrawlRequest" }, "CreateBotRequest": { "properties": { "name": { "type": "string", "title": "Name", "default": "AI Assistant" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Prompt" }, "bant_enabled": { "type": "boolean", "title": "Bant Enabled", "default": true }, "allowed_domains": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Domains" }, "domain_check_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Domain Check Enabled" } }, "type": "object", "title": "CreateBotRequest" }, "CreateCannedResponseRequest": { "properties": { "title": { "type": "string", "title": "Title" }, "content": { "type": "string", "title": "Content" }, "shortcut": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Shortcut" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } }, "type": "object", "required": [ "title", "content" ], "title": "CreateCannedResponseRequest" }, "CreateClientRequest": { "properties": { "name": { "type": "string", "title": "Name" }, "email": { "type": "string", "title": "Email" }, "password": { "type": "string", "title": "Password" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" } }, "type": "object", "required": [ "name", "email", "password" ], "title": "CreateClientRequest" }, "CreateCodeRequest": { "properties": { "code": { "type": "string", "maxLength": 20, "minLength": 3, "title": "Code" }, "label": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Label" }, "affiliate_commission_pct": { "anyOf": [ { "type": "number", "maximum": 100.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Affiliate Commission Pct" }, "customer_discount_pct": { "anyOf": [ { "type": "number", "maximum": 100.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Customer Discount Pct" } }, "type": "object", "required": [ "code" ], "title": "CreateCodeRequest" }, "CreateDepartmentRequest": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" } }, "type": "object", "required": [ "name" ], "title": "CreateDepartmentRequest" }, "CreateOperatorRequest": { "properties": { "name": { "type": "string", "title": "Name" }, "email": { "type": "string", "title": "Email" }, "password": { "type": "string", "title": "Password" }, "role": { "type": "string", "title": "Role", "default": "operator" }, "department_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Department Id" } }, "type": "object", "required": [ "name", "email", "password" ], "title": "CreateOperatorRequest" }, "CreatePlanRequest": { "properties": { "name": { "type": "string", "title": "Name" }, "slug": { "type": "string", "title": "Slug" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "pricing_model": { "type": "string", "title": "Pricing Model", "default": "per_operator" }, "currency": { "type": "string", "title": "Currency", "default": "INR" }, "monthly_price_cents": { "type": "integer", "title": "Monthly Price Cents", "default": 0 }, "annual_price_cents": { "type": "integer", "title": "Annual Price Cents", "default": 0 }, "monthly_price_usd_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Monthly Price Usd Cents" }, "annual_price_usd_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Annual Price Usd Cents" }, "extra_seat_price_usd_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Extra Seat Price Usd Cents" }, "annual_discount_percent": { "type": "integer", "title": "Annual Discount Percent", "default": 30 }, "trial_days": { "type": "integer", "title": "Trial Days", "default": 14 }, "limits": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Limits" }, "features": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Features" }, "marketing": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Marketing" }, "overage_rate_cents": { "type": "integer", "title": "Overage Rate Cents", "default": 0 }, "credits_per_month": { "type": "integer", "title": "Credits Per Month", "default": 0 }, "included_operator_seats": { "type": "integer", "title": "Included Operator Seats", "default": 1 }, "extra_seat_price_cents": { "type": "integer", "title": "Extra Seat Price Cents", "default": 1500 }, "razorpay_plan_id_monthly": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Razorpay Plan Id Monthly" }, "razorpay_plan_id_annual": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Razorpay Plan Id Annual" }, "is_active": { "type": "boolean", "title": "Is Active", "default": true }, "is_default": { "type": "boolean", "title": "Is Default", "default": false }, "sort_order": { "type": "integer", "title": "Sort Order", "default": 0 } }, "type": "object", "required": [ "name", "slug" ], "title": "CreatePlanRequest" }, "CreateWebhookRequest": { "properties": { "url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Url" }, "events": { "items": { "type": "string" }, "type": "array", "title": "Events" }, "is_active": { "type": "boolean", "title": "Is Active", "default": true } }, "type": "object", "required": [ "url", "events" ], "title": "CreateWebhookRequest" }, "CreditsGrant": { "properties": { "delta": { "type": "integer", "title": "Delta" }, "reason": { "type": "string", "maxLength": 500, "minLength": 3, "title": "Reason" } }, "type": "object", "required": [ "delta", "reason" ], "title": "CreditsGrant" }, "CurrentUserResponse": { "properties": { "id": { "type": "integer", "title": "Id" }, "kind": { "type": "string", "title": "Kind" }, "name": { "type": "string", "title": "Name" }, "email": { "type": "string", "title": "Email" }, "pending_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pending Email" }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Name" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" }, "created_at": { "type": "string", "title": "Created At" }, "bot_count": { "type": "integer", "title": "Bot Count" }, "is_superadmin": { "type": "boolean", "title": "Is Superadmin", "default": false }, "is_online": { "type": "boolean", "title": "Is Online", "default": false }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" }, "is_affiliate": { "type": "boolean", "title": "Is Affiliate", "default": false }, "affiliate_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Affiliate Id" }, "is_affiliate_only": { "type": "boolean", "title": "Is Affiliate Only", "default": false }, "trial": { "anyOf": [ { "$ref": "#/components/schemas/TrialStatePayload" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "kind", "name", "email", "created_at", "bot_count" ], "title": "CurrentUserResponse", "description": "Profile payload for the authenticated principal (TopBar profile dropdown).\n\nWorks for both clients (admins) and operators. The ``kind`` discriminator\ntells the UI which fields are meaningful \u2014 operators don't own bots\ndirectly, so ``bot_count`` reflects the bots in their workspace (the\nclient they belong to). For clients ``role`` is None; for operators\n``role`` is one of ``owner | admin | operator``.\n\nExposes only the small set of profile fields the admin app needs to\nrender the user menu \u2014 never sensitive data (no api_key, no password\nhash)." }, "DocumentPageItem": { "properties": { "url": { "type": "string", "title": "Url" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "chunk_count": { "type": "integer", "title": "Chunk Count" }, "ingested_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ingested At" } }, "type": "object", "required": [ "url", "title", "chunk_count", "ingested_at" ], "title": "DocumentPageItem" }, "DocumentPagesResponse": { "properties": { "domain": { "type": "string", "title": "Domain" }, "total_pages": { "type": "integer", "title": "Total Pages" }, "total_chunks": { "type": "integer", "title": "Total Chunks" }, "pages": { "items": { "$ref": "#/components/schemas/DocumentPageItem" }, "type": "array", "title": "Pages" } }, "type": "object", "required": [ "domain", "total_pages", "total_chunks", "pages" ], "title": "DocumentPagesResponse" }, "FeedbackRequest": { "properties": { "feedback": { "type": "integer", "maximum": 1.0, "minimum": -1.0, "title": "Feedback", "description": "1 for positive, -1 for negative" } }, "type": "object", "required": [ "feedback" ], "title": "FeedbackRequest" }, "FlagWrite": { "properties": { "value": { "title": "Value" } }, "type": "object", "required": [ "value" ], "title": "FlagWrite" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HandoffRequest": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "department_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Department Id" } }, "type": "object", "required": [ "session_id" ], "title": "HandoffRequest" }, "InviteAffiliateRequest": { "properties": { "email": { "type": "string", "title": "Email" }, "max_active_codes": { "anyOf": [ { "type": "integer", "maximum": 100.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Max Active Codes" }, "commission_pct": { "anyOf": [ { "type": "number", "maximum": 100.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Commission Pct" } }, "type": "object", "required": [ "email" ], "title": "InviteAffiliateRequest" }, "InviteResponse": { "properties": { "kind": { "type": "string", "title": "Kind" }, "affiliate": { "anyOf": [ { "$ref": "#/components/schemas/AffiliateRow" }, { "type": "null" } ] }, "invite": { "anyOf": [ { "$ref": "#/components/schemas/PendingInviteRow" }, { "type": "null" } ] } }, "type": "object", "required": [ "kind" ], "title": "InviteResponse", "description": "Discriminated response from POST /superadmin/affiliates.\n\n``kind`` selects which of ``affiliate`` or ``invite`` carries the payload:\n * ``\"instant\"`` \u2192 ``affiliate`` is set; recipient was already a Client\n * ``\"pending_invite\"`` \u2192 ``invite`` is set; magic-link email sent" }, "LeadCaptureRequest": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name" }, "email": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Email" }, "phone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "title": "Phone" }, "company": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Company" } }, "type": "object", "required": [ "session_id" ], "title": "LeadCaptureRequest" }, "LoginRequest": { "properties": { "email": { "type": "string", "title": "Email" }, "password": { "type": "string", "title": "Password" } }, "type": "object", "required": [ "email", "password" ], "title": "LoginRequest" }, "LoginResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token" }, "token_type": { "type": "string", "title": "Token Type", "default": "bearer" }, "client_id": { "type": "integer", "title": "Client Id" }, "name": { "type": "string", "title": "Name" }, "is_superadmin": { "type": "boolean", "title": "Is Superadmin" }, "is_verified": { "type": "boolean", "title": "Is Verified", "default": true }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Name" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" } }, "type": "object", "required": [ "access_token", "client_id", "name", "is_superadmin" ], "title": "LoginResponse" }, "MeResponse": { "properties": { "id": { "type": "integer", "title": "Id" }, "max_active_codes": { "type": "integer", "title": "Max Active Codes" }, "commission_pct": { "type": "number", "title": "Commission Pct" }, "commission_bps": { "type": "integer", "title": "Commission Bps" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id", "max_active_codes", "commission_pct", "commission_bps", "created_at" ], "title": "MeResponse" }, "MeetingBookedRequest": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "booking_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Booking Url" }, "meeting_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Meeting Time" }, "attendee_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Attendee Email" } }, "type": "object", "required": [ "session_id" ], "title": "MeetingBookedRequest" }, "ModelConfigPatch": { "properties": { "primary_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Model" }, "fallback_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fallback Model" }, "gate_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gate Model" }, "chunk_size": { "anyOf": [ { "type": "integer", "maximum": 8000.0, "minimum": 200.0 }, { "type": "null" } ], "title": "Chunk Size" }, "chunk_overlap": { "anyOf": [ { "type": "integer", "maximum": 2000.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Chunk Overlap" }, "rerank_top_n": { "anyOf": [ { "type": "integer", "maximum": 20.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Rerank Top N" }, "relevance_threshold": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Relevance Threshold" }, "embed_concurrency": { "anyOf": [ { "type": "integer", "maximum": 64.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Embed Concurrency" }, "crawl_provider_primary": { "anyOf": [ { "type": "string", "enum": [ "spider", "jina" ] }, { "type": "null" } ], "title": "Crawl Provider Primary" }, "jina_fetch_concurrency": { "anyOf": [ { "type": "integer", "maximum": 50.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Jina Fetch Concurrency" }, "spider_fetch_concurrency": { "anyOf": [ { "type": "integer", "maximum": 50.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Spider Fetch Concurrency" } }, "type": "object", "title": "ModelConfigPatch" }, "OfflineMessagePatch": { "properties": { "status": { "type": "string", "title": "Status" } }, "type": "object", "required": [ "status" ], "title": "OfflineMessagePatch" }, "OperatorChangePasswordRequest": { "properties": { "current_password": { "type": "string", "title": "Current Password" }, "new_password": { "type": "string", "title": "New Password" } }, "type": "object", "required": [ "current_password", "new_password" ], "title": "OperatorChangePasswordRequest" }, "OperatorLoginRequest": { "properties": { "email": { "type": "string", "title": "Email" }, "password": { "type": "string", "title": "Password" } }, "type": "object", "required": [ "email", "password" ], "title": "OperatorLoginRequest" }, "OperatorLoginResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token" }, "token_type": { "type": "string", "title": "Token Type", "default": "bearer" }, "operator_id": { "type": "integer", "title": "Operator Id" }, "client_id": { "type": "integer", "title": "Client Id" }, "default_bot_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Default Bot Id" }, "name": { "type": "string", "title": "Name" }, "role": { "type": "string", "title": "Role" }, "department_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Department Id" }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Name" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" } }, "type": "object", "required": [ "access_token", "operator_id", "client_id", "name", "role" ], "title": "OperatorLoginResponse" }, "PendingInviteRow": { "properties": { "id": { "type": "integer", "title": "Id" }, "email": { "type": "string", "title": "Email" }, "max_active_codes": { "type": "integer", "title": "Max Active Codes" }, "invited_by": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Invited By" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id", "email", "max_active_codes", "invited_by", "expires_at", "created_at" ], "title": "PendingInviteRow" }, "PlatformFeedbackCreate": { "properties": { "message": { "type": "string", "title": "Message" }, "attachment_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Attachment Url" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" }, "type": { "type": "string", "title": "Type", "default": "other" }, "area": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Area" }, "severity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Severity" }, "context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Context" }, "attachments": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Attachments" } }, "type": "object", "required": [ "message" ], "title": "PlatformFeedbackCreate" }, "PlatformFeedbackUpdate": { "properties": { "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "admin_response": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Admin Response" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "area": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Area" }, "severity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Severity" } }, "type": "object", "title": "PlatformFeedbackUpdate" }, "PricingContentRequest": { "properties": { "faq": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Faq" }, "feature_matrix": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Feature Matrix" }, "topup_packs": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Topup Packs" }, "credit_costs": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Credit Costs" } }, "type": "object", "title": "PricingContentRequest" }, "PricingDistribution": { "properties": { "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency" }, "paying_referrals": { "type": "integer", "title": "Paying Referrals" }, "monthly_total_cents": { "type": "integer", "title": "Monthly Total Cents" }, "monthly_affiliate_cents": { "type": "integer", "title": "Monthly Affiliate Cents" }, "monthly_customer_saved_cents": { "type": "integer", "title": "Monthly Customer Saved Cents" }, "monthly_platform_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Monthly Platform Cents" } }, "type": "object", "required": [ "currency", "paying_referrals", "monthly_total_cents", "monthly_affiliate_cents", "monthly_customer_saved_cents" ], "title": "PricingDistribution", "description": "Aggregate monthly $ rolled up across every paying referral.\n\nLets the affiliate see \"your code is pulling ~$X/mo from N customers\"\nat a glance without summing the per-row cards by eye." }, "PushSubscribeRequest": { "properties": { "endpoint": { "type": "string", "title": "Endpoint" }, "keys": { "$ref": "#/components/schemas/PushSubscriptionKeys" } }, "type": "object", "required": [ "endpoint", "keys" ], "title": "PushSubscribeRequest" }, "PushSubscriptionKeys": { "properties": { "p256dh": { "type": "string", "title": "P256Dh" }, "auth": { "type": "string", "title": "Auth" } }, "type": "object", "required": [ "p256dh", "auth" ], "title": "PushSubscriptionKeys" }, "QualificationOverrideRequest": { "properties": { "dimension": { "type": "string", "title": "Dimension" }, "score": { "type": "integer", "minimum": 0.0, "title": "Score" } }, "type": "object", "required": [ "dimension", "score" ], "title": "QualificationOverrideRequest" }, "RecrawlStatusResponse": { "properties": { "enabled": { "type": "boolean", "title": "Enabled" }, "cadence_days": { "type": "integer", "title": "Cadence Days" }, "feature_available": { "type": "boolean", "title": "Feature Available" }, "current_plan": { "type": "string", "title": "Current Plan" }, "next_recrawl_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Recrawl At" }, "last_recrawl_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Recrawl At" }, "last_recrawl_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Recrawl Status" }, "last_recrawl_summary": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Last Recrawl Summary" }, "sources_count": { "type": "integer", "title": "Sources Count" }, "recrawl_history": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Recrawl History" } }, "type": "object", "required": [ "enabled", "cadence_days", "feature_available", "current_plan", "next_recrawl_at", "last_recrawl_at", "last_recrawl_status", "last_recrawl_summary", "sources_count", "recrawl_history" ], "title": "RecrawlStatusResponse" }, "RecrawlUpdateRequest": { "properties": { "enabled": { "type": "boolean", "title": "Enabled" } }, "type": "object", "required": [ "enabled" ], "title": "RecrawlUpdateRequest" }, "ReferralPricing": { "properties": { "plan_slug": { "type": "string", "title": "Plan Slug" }, "currency": { "type": "string", "title": "Currency" }, "full_price_cents": { "type": "integer", "title": "Full Price Cents" }, "paid_cents": { "type": "integer", "title": "Paid Cents" }, "affiliate_earns_cents": { "type": "integer", "title": "Affiliate Earns Cents" }, "customer_saved_cents": { "type": "integer", "title": "Customer Saved Cents" }, "platform_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Platform Cents" } }, "type": "object", "required": [ "plan_slug", "currency", "full_price_cents", "paid_cents", "affiliate_earns_cents", "customer_saved_cents" ], "title": "ReferralPricing", "description": "Dollar-amount split for a single referred customer's monthly bill.\n\nCents are the minor unit of ``currency``. Values are 0 when the customer\nhas no paid subscription yet (Free tier, never converted, or paused)." }, "ReferralRow": { "properties": { "client_id": { "type": "integer", "title": "Client Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "email": { "type": "string", "title": "Email" }, "attributed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Attributed At" }, "pricing": { "$ref": "#/components/schemas/ReferralPricing" } }, "type": "object", "required": [ "client_id", "name", "email", "attributed_at", "pricing" ], "title": "ReferralRow" }, "ReferralStatusResponse": { "properties": { "attributed": { "type": "boolean", "title": "Attributed" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code" }, "discount_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Discount Pct" } }, "type": "object", "required": [ "attributed" ], "title": "ReferralStatusResponse" }, "RegisterRequest": { "properties": { "name": { "type": "string", "title": "Name" }, "email": { "type": "string", "title": "Email" }, "password": { "type": "string", "title": "Password" }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Name" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" }, "billing_country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Billing Country" }, "referral_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Referral Code" } }, "type": "object", "required": [ "name", "email", "password" ], "title": "RegisterRequest" }, "RegisterResponse": { "properties": { "access_token": { "type": "string", "title": "Access Token" }, "token_type": { "type": "string", "title": "Token Type", "default": "bearer" }, "client_id": { "type": "integer", "title": "Client Id" }, "name": { "type": "string", "title": "Name" }, "is_superadmin": { "type": "boolean", "title": "Is Superadmin", "default": false }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Name" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" }, "message": { "type": "string", "title": "Message", "default": "Account created successfully." }, "trial": { "anyOf": [ { "$ref": "#/components/schemas/TrialStatePayload" }, { "type": "null" } ] } }, "type": "object", "required": [ "access_token", "client_id", "name" ], "title": "RegisterResponse" }, "RequestPasswordResetRequest": { "properties": { "email": { "type": "string", "title": "Email" } }, "type": "object", "required": [ "email" ], "title": "RequestPasswordResetRequest" }, "ResendVerificationRequest": { "properties": { "email": { "type": "string", "title": "Email" } }, "type": "object", "required": [ "email" ], "title": "ResendVerificationRequest" }, "ResetPasswordRequest": { "properties": { "email": { "type": "string", "title": "Email" }, "otp": { "type": "string", "title": "Otp" }, "new_password": { "type": "string", "title": "New Password" } }, "type": "object", "required": [ "email", "otp", "new_password" ], "title": "ResetPasswordRequest" }, "ResumeSubscriptionRequest": { "properties": { "bot_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } }, "type": "object", "title": "ResumeSubscriptionRequest" }, "SeatChangeRequest": { "properties": { "delta": { "type": "integer", "title": "Delta" }, "bot_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } }, "type": "object", "required": [ "delta" ], "title": "SeatChangeRequest" }, "SellerProfileBody": { "properties": { "legal_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legal Name" }, "trade_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trade Name" }, "gstin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gstin" }, "address_lines": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Address Lines" }, "state_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State Code" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country" }, "sac_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sac Code" }, "tax_rate_bps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tax Rate Bps" }, "price_inclusive": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Price Inclusive" }, "lut_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Lut Active" }, "lut_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lut Number" }, "invoice_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invoice Prefix" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Url" } }, "type": "object", "title": "SellerProfileBody" }, "SetStatusRequest": { "properties": { "is_online": { "type": "boolean", "title": "Is Online" } }, "type": "object", "required": [ "is_online" ], "title": "SetStatusRequest" }, "StartTrialRequest": { "properties": { "plan_slug": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Plan Slug" } }, "type": "object", "required": [ "plan_slug" ], "title": "StartTrialRequest", "description": "Body for ``POST /subscriptions/start-trial``.\n\nThe slug is the public plan identifier the pricing page renders against\n(``starter`` / ``standard``). The slug must point at an active plan with\n``trial_days > 0`` \u2014 the free plan and enterprise tier are intentionally\nexcluded." }, "SubmitOfflineMessageRequest": { "properties": { "bot_key": { "type": "string", "maxLength": 100, "title": "Bot Key" }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name" }, "email": { "type": "string", "maxLength": 320, "title": "Email" }, "phone": { "anyOf": [ { "type": "string", "maxLength": 30 }, { "type": "null" } ], "title": "Phone" }, "message": { "type": "string", "maxLength": 5000, "minLength": 1, "title": "Message" }, "session_id": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Session Id" }, "department_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Department Id" } }, "type": "object", "required": [ "bot_key", "name", "email", "message" ], "title": "SubmitOfflineMessageRequest" }, "TopupRequest": { "properties": { "amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Amount" }, "pack_usd": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pack Usd" }, "bot_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Bot Id" } }, "type": "object", "title": "TopupRequest", "description": "Top-up purchase request.\n\n``amount`` is the pack amount matching one of the configured packs in\n``pricing_config.topup_packs``. ``pack_usd`` is kept as a backward-compat\nalias for older admin builds \u2014 at least one of the two must be provided.\n\n``bot_id`` scopes the purchase to a specific per-bot ledger. Omit\n(or pass null) to top up the account-level client pool \u2014 that's the\ncorrect shape for Free / legacy-pooled bots whose usage drains\nshared credits. Per-bot subscriptions must always pass their bot_id\nso the credits land in the right isolated bucket." }, "TopupVerifyRequest": { "properties": { "razorpay_order_id": { "type": "string", "title": "Razorpay Order Id" }, "razorpay_payment_id": { "type": "string", "title": "Razorpay Payment Id" }, "razorpay_signature": { "type": "string", "title": "Razorpay Signature" } }, "type": "object", "required": [ "razorpay_order_id", "razorpay_payment_id", "razorpay_signature" ], "title": "TopupVerifyRequest", "description": "Razorpay Checkout success callback verification.\n\nThe frontend sends the trio Razorpay returns in its handler callback;\nwe verify the HMAC server-side to make sure the success was genuinely\nsigned by Razorpay (defence against tampered modal responses).\n\nThe credit grant itself happens via the Razorpay webhook \u2014 this\nendpoint just confirms the modal closure to the user." }, "TranscriptEmailRequest": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "recipient_email": { "type": "string", "title": "Recipient Email" } }, "type": "object", "required": [ "session_id", "recipient_email" ], "title": "TranscriptEmailRequest" }, "TransferRequest": { "properties": { "target_operator_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Target Operator Id" }, "target_department_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Target Department Id" } }, "type": "object", "title": "TransferRequest" }, "TrialStatePayload": { "properties": { "status": { "type": "string", "title": "Status" }, "trial_end_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trial End At" }, "days_remaining": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Days Remaining" }, "credits_granted": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Credits Granted" } }, "type": "object", "required": [ "status" ], "title": "TrialStatePayload", "description": "Subset of subscription state the dashboard needs to render the trial banner.\n\nAlways populated for clients that landed on a trialing subscription at\nsignup; ``None`` for accounts created without a trial (super-admin\nseeded, legacy free-tier, etc). The admin app treats ``None`` as\n\"no trial UI\" rather than zero-day urgency." }, "UpdateAffiliateRequest": { "properties": { "max_active_codes": { "anyOf": [ { "type": "integer", "maximum": 100.0, "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Max Active Codes" }, "commission_pct": { "anyOf": [ { "type": "number", "maximum": 100.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Commission Pct" }, "active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Active" } }, "type": "object", "title": "UpdateAffiliateRequest" }, "UpdateBotRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "system_prompt": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "System Prompt" }, "brand_tone": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Brand Tone" }, "company_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Company Name" }, "company_description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Company Description" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" }, "bot_logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bot Logo" }, "launcher_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Launcher Name" }, "launcher_logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Launcher Logo" }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Color" }, "background_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Background Color" }, "header_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Header Color" }, "user_bubble_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Bubble Color" }, "bant_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Bant Enabled" }, "bant_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Bant Config" }, "qualification_framework": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Qualification Framework" }, "relevance_threshold": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Relevance Threshold" }, "avatar_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Type" }, "orb_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Orb Color" }, "lead_form_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Lead Form Enabled" }, "lead_form_fields": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Lead Form Fields" }, "notification_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notification Email" }, "notification_emails": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Notification Emails" }, "reply_to_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reply To Email" }, "email_on_qualified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Email On Qualified" }, "email_on_handoff": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Email On Handoff" }, "email_on_offline": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Email On Offline" }, "email_visitor_confirmation": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Email Visitor Confirmation" }, "live_chat_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Live Chat Enabled" }, "operator_timeout_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Operator Timeout Seconds" }, "live_chat_queue_timeout_seconds": { "anyOf": [ { "type": "integer", "maximum": 600.0, "minimum": 5.0 }, { "type": "null" } ], "title": "Live Chat Queue Timeout Seconds" }, "live_chat_max_queue_size": { "anyOf": [ { "type": "integer", "maximum": 100.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Live Chat Max Queue Size" }, "business_hours": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Business Hours" }, "feature_flags": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Feature Flags" }, "widget_messages": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Widget Messages" }, "widget_config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Widget Config" }, "branding_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branding Text" }, "branding_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Branding Url" }, "welcome_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Welcome Title" }, "welcome_subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Welcome Subtitle" }, "waiting_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Waiting Message" }, "offline_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Offline Message" }, "handoff_delay_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Handoff Delay Seconds" }, "calendly_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Calendly Url" }, "meeting_booking_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Meeting Booking Enabled" }, "meeting_provider": { "anyOf": [ { "type": "string", "pattern": "^(calendly|zcal|calcom)$" }, { "type": "null" } ], "title": "Meeting Provider" }, "zcal_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Zcal Url" }, "calcom_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Calcom Url" }, "services": { "anyOf": [ { "items": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "string" } ] }, "type": "array" }, { "type": "null" } ], "title": "Services" }, "services_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Services Url" }, "allowed_domains": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Domains" }, "domain_check_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Domain Check Enabled" } }, "type": "object", "title": "UpdateBotRequest" }, "UpdateCannedResponseRequest": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content" }, "shortcut": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Shortcut" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category" } }, "type": "object", "title": "UpdateCannedResponseRequest" }, "UpdateCodeRequest": { "properties": { "code": { "anyOf": [ { "type": "string", "maxLength": 20, "minLength": 3 }, { "type": "null" } ], "title": "Code" }, "label": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Label" }, "active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Active" }, "affiliate_commission_pct": { "anyOf": [ { "type": "number", "maximum": 100.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Affiliate Commission Pct" }, "customer_discount_pct": { "anyOf": [ { "type": "number", "maximum": 100.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Customer Discount Pct" } }, "type": "object", "title": "UpdateCodeRequest" }, "UpdateDepartmentRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "business_hours": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Business Hours" } }, "type": "object", "title": "UpdateDepartmentRequest" }, "UpdateOfflineMessageRequest": { "properties": { "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, "type": "object", "title": "UpdateOfflineMessageRequest" }, "UpdateOperatorRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Role" }, "department_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Department Id" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Url" }, "max_concurrent_chats": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Concurrent Chats" }, "notification_preferences": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Notification Preferences" } }, "type": "object", "title": "UpdateOperatorRequest" }, "UpdatePlanRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "pricing_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pricing Model" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency" }, "monthly_price_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Monthly Price Cents" }, "annual_price_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Annual Price Cents" }, "monthly_price_usd_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Monthly Price Usd Cents" }, "annual_price_usd_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Annual Price Usd Cents" }, "extra_seat_price_usd_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Extra Seat Price Usd Cents" }, "annual_discount_percent": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Annual Discount Percent" }, "trial_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Trial Days" }, "limits": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Limits" }, "features": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Features" }, "marketing": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Marketing" }, "overage_rate_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Overage Rate Cents" }, "credits_per_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Credits Per Month" }, "included_operator_seats": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Included Operator Seats" }, "extra_seat_price_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Extra Seat Price Cents" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" }, "is_default": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Default" }, "sort_order": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sort Order" }, "razorpay_plan_id_monthly": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Razorpay Plan Id Monthly" }, "razorpay_plan_id_annual": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Razorpay Plan Id Annual" } }, "type": "object", "title": "UpdatePlanRequest" }, "UpdateSubscriptionRequest": { "properties": { "plan_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Plan Id" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "operator_quantity": { "anyOf": [ { "type": "integer", "maximum": 1000.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Operator Quantity" }, "billing_cycle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Billing Cycle" }, "extend_trial_days": { "anyOf": [ { "type": "integer", "maximum": 365.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Extend Trial Days" } }, "type": "object", "title": "UpdateSubscriptionRequest" }, "UpdateWebhookRequest": { "properties": { "url": { "anyOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ], "title": "Url" }, "events": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Events" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active" } }, "type": "object", "title": "UpdateWebhookRequest" }, "UploadUrlRequest": { "properties": { "filename": { "type": "string", "title": "Filename" }, "content_type": { "type": "string", "title": "Content Type" }, "size": { "type": "integer", "title": "Size" }, "session_id": { "type": "string", "title": "Session Id" } }, "type": "object", "required": [ "filename", "content_type", "size", "session_id" ], "title": "UploadUrlRequest" }, "ValidateCodeResponse": { "properties": { "valid": { "type": "boolean", "title": "Valid" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" } }, "type": "object", "required": [ "valid" ], "title": "ValidateCodeResponse" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VerifyEmailRequest": { "properties": { "email": { "type": "string", "title": "Email" }, "otp": { "type": "string", "title": "Otp" } }, "type": "object", "required": [ "email", "otp" ], "title": "VerifyEmailRequest" }, "VerifyRazorpaySubscriptionRequest": { "properties": { "razorpay_payment_id": { "type": "string", "title": "Razorpay Payment Id" }, "razorpay_subscription_id": { "type": "string", "title": "Razorpay Subscription Id" }, "razorpay_signature": { "type": "string", "title": "Razorpay Signature" } }, "type": "object", "required": [ "razorpay_payment_id", "razorpay_subscription_id", "razorpay_signature" ], "title": "VerifyRazorpaySubscriptionRequest" }, "VisitorRatingRequest": { "properties": { "rating": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Rating" }, "resolved": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Resolved" } }, "type": "object", "title": "VisitorRatingRequest" }, "WebhookRegistrationPatch": { "properties": { "is_active": { "type": "boolean", "title": "Is Active" } }, "type": "object", "required": [ "is_active" ], "title": "WebhookRegistrationPatch" } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } } }