{"openapi":"3.1.0","info":{"title":"HelpBot API Reference","version":"1.0.0","description":"The HelpBot REST API lets you integrate AI-powered FAQ chat into any frontend. All endpoints live under /api/v1/ and accept authentication via Bearer token or apiKey parameter."},"servers":[{"url":"https://www.helpbot.saastemly.com","description":"Production"}],"tags":[{"name":"Chat","description":"Send questions, receive AI answers, submit feedback, and escalate to humans."},{"name":"Sources","description":"Manage FAQ sources programmatically (Scale plan required)."},{"name":"Widget","description":"Retrieve widget display configuration (colors, labels, position)."},{"name":"Analytics","description":"Usage statistics, daily activity, and unanswered question insights (Growth or Scale plan required)."},{"name":"Webhooks","description":"Register callback URLs to receive real-time event notifications (Growth or Scale plan required)."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key as Bearer token. Find yours in Dashboard → Sites → (your site). Alternatively pass apiKey in the request body or query string."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","example":"Unauthorized"}}}}},"paths":{"/api/v1/chat":{"post":{"tags":["Chat"],"summary":"Ask a question","description":"Submit a question and receive an AI-generated answer based on your indexed FAQ sources. Supports language selection. Consumes credits from your monthly allowance.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"question":{"type":"string","maxLength":1000,"description":"The question to ask.","example":"How do I reset my password?"},"apiKey":{"description":"Your API key. Can also be passed as a Bearer token in the Authorization header.","example":"wk_live_abc123","type":"string"},"sessionId":{"description":"Session identifier for conversation grouping. Auto-generated if omitted.","example":"user_session_42","type":"string"},"language":{"description":"ISO language code or \"auto\". Overrides the dashboard language setting.","example":"en","type":"string"}},"required":["question"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"answer":{"type":"string","description":"AI-generated answer."},"sources":{"type":"array","items":{"type":"string"},"description":"Source titles used to generate the answer."},"conversationId":{"type":"string","description":"ID of the stored conversation record."}},"required":["answer","sources","conversationId"],"additionalProperties":false}}}},"400":{"description":"Missing or invalid question field."},"401":{"description":"Invalid API key."},"429":{"description":"Monthly credit limit reached."},"500":{"description":"Internal server error."}}}},"/api/v1/sources":{"get":{"tags":["Sources"],"summary":"List FAQ sources","description":"Returns all FAQ sources associated with your site. Requires Scale plan.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"abc123"},"url":{"type":"string","format":"uri","example":"https://example.com/faq"},"status":{"type":"string","enum":["pending","scraping","indexed","failed"],"example":"indexed"},"documentCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"example":42},"lastScrapedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}],"example":"2024-01-15T10:30:00Z"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","example":"2024-01-14T08:00:00Z"}},"required":["id","url","status","documentCount","lastScrapedAt","createdAt"],"additionalProperties":false},"description":"Array of source objects."}},"required":["sources"],"additionalProperties":false}}}},"401":{"description":"Invalid API key."},"403":{"description":"Plan not allowed."},"500":{"description":"Internal server error."}}},"post":{"tags":["Sources"],"summary":"Add a FAQ source","description":"Creates a new FAQ source with status: pending. Requires Scale plan. Poll GET /api/v1/sources to check when status becomes indexed.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string","format":"uri","description":"The URL to scrape for FAQ content.","example":"https://example.com/help"}},"required":["url"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"source":{"type":"object","properties":{"id":{"type":"string","description":"The new source ID."},"url":{"type":"string","description":"The URL provided."},"status":{"type":"string","enum":["pending"],"description":"Always pending on creation."}},"required":["id","url","status"],"additionalProperties":false},"message":{"type":"string","description":"Human-readable confirmation."}},"required":["source","message"],"additionalProperties":false}}}},"400":{"description":"Missing url field."},"401":{"description":"Invalid API key."},"403":{"description":"Plan not allowed."},"500":{"description":"Internal server error."}}},"delete":{"tags":["Sources"],"summary":"Delete a FAQ source","description":"Permanently removes a FAQ source by ID. Requires Scale plan.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"description":"The ID of the source to delete.","example":"src_xyz789","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"deleted":{"type":"boolean","description":"Always true on success."}},"required":["deleted"],"additionalProperties":false}}}},"400":{"description":"Missing id query parameter."},"401":{"description":"Invalid API key."},"403":{"description":"Plan not allowed."},"404":{"description":"Source not found or belongs to a different site."},"500":{"description":"Internal server error."}}}},"/api/v1/config":{"get":{"tags":["Widget"],"summary":"Get widget configuration","description":"Returns the full display configuration for a widget — colors, labels, position, bot name, and all customisable text strings.","security":[{"bearerAuth":[]}],"parameters":[{"name":"apiKey","in":"query","required":false,"description":"Your API key (alternative to Authorization header).","example":"wk_live_abc123","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"primaryColor":{"type":"string","description":"Hex color for the widget primary accent."},"primaryForeground":{"type":"string","description":"Foreground color on primary."},"backgroundColor":{"type":"string","description":"Widget background color."},"foregroundColor":{"type":"string","description":"Widget text color."},"secondaryColor":{"type":"string","description":"Secondary background color."},"secondaryForeground":{"type":"string","description":"Secondary text color."},"position":{"type":"string","enum":["bottom-right","bottom-left"],"description":"Widget position on screen."},"greeting":{"type":"string","description":"Opening message shown to users."},"botName":{"type":"string","description":"Display name shown in the widget header."},"showBranding":{"type":"boolean","description":"Whether HelpBot branding is shown (Scale plan can hide)."},"aiLanguage":{"type":"string","description":"Language code (e.g. \"en\", \"ar\") or \"auto\"."},"inputPlaceholder":{"type":"string","description":"Placeholder text for the input field."},"typingText":{"type":"string","description":"Text shown while AI is generating a response."},"onlineText":{"type":"string","description":"Status indicator text."},"handoffText":{"type":"string","description":"Label for the human handoff button."},"handoffSentText":{"type":"string","description":"Confirmation message after handoff request."},"emailPlaceholder":{"type":"string","description":"Placeholder for the email input during handoff."},"emailSendText":{"type":"string","description":"Label for the send email button."},"emailSkipText":{"type":"string","description":"Label for the skip email button."},"feedbackYesText":{"type":"string","description":"Thumbs-up feedback label."},"feedbackNoText":{"type":"string","description":"Thumbs-down feedback label."},"errorText":{"type":"string","description":"Generic error message."},"networkErrorText":{"type":"string","description":"Network connectivity error message."}},"required":["primaryColor","primaryForeground","backgroundColor","foregroundColor","secondaryColor","secondaryForeground","position","greeting","botName","showBranding","aiLanguage","inputPlaceholder","typingText","onlineText","handoffText","handoffSentText","emailPlaceholder","emailSendText","emailSkipText","feedbackYesText","feedbackNoText","errorText","networkErrorText"],"additionalProperties":false}}}},"401":{"description":"Invalid API key."},"500":{"description":"Internal server error."}}},"patch":{"tags":["Widget"],"summary":"Update widget configuration","description":"Update one or more widget configuration fields. Only send the fields you want to change — omitted fields keep their current values. Setting showBranding to false requires the Scale plan.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"apiKey":{"description":"Your API key. Can also be passed as a Bearer token in the Authorization header.","example":"wk_live_abc123","type":"string"},"primaryColor":{"description":"Hex color for the widget primary accent.","example":"#4f46e5","type":"string"},"primaryForeground":{"description":"Foreground color on primary.","example":"#ffffff","type":"string"},"backgroundColor":{"description":"Widget background color.","example":"#ffffff","type":"string"},"foregroundColor":{"description":"Widget text color.","example":"#1f2937","type":"string"},"secondaryColor":{"description":"Secondary background color.","example":"#f3f4f6","type":"string"},"secondaryForeground":{"description":"Secondary text color.","example":"#1f2937","type":"string"},"position":{"description":"Widget position on screen.","type":"string","enum":["bottom-right","bottom-left"]},"greeting":{"description":"Opening message shown to users.","example":"Hi! How can I help you today?","type":"string"},"botName":{"description":"Display name shown in the widget header.","example":"HelpBot","type":"string"},"showBranding":{"description":"Show HelpBot branding. Setting to false requires Scale plan.","type":"boolean"},"aiLanguage":{"description":"Language code (e.g. \"en\", \"ar\") or \"auto\".","example":"auto","type":"string"},"inputPlaceholder":{"description":"Input placeholder text.","type":"string"},"typingText":{"description":"Typing indicator text.","type":"string"},"onlineText":{"description":"Status indicator text.","type":"string"},"handoffText":{"description":"Handoff button label.","type":"string"},"handoffSentText":{"description":"Confirmation after handoff.","type":"string"},"emailPlaceholder":{"description":"Email input placeholder.","type":"string"},"emailSendText":{"description":"Email send button label.","type":"string"},"emailSkipText":{"description":"Email skip button label.","type":"string"},"feedbackYesText":{"description":"Positive feedback label.","type":"string"},"feedbackNoText":{"description":"Negative feedback label.","type":"string"},"errorText":{"description":"Generic error message.","type":"string"},"networkErrorText":{"description":"Network error message.","type":"string"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"updated":{"type":"array","items":{"type":"string"},"description":"List of field names that were updated."},"config":{"type":"object","properties":{"primaryColor":{"type":"string","description":"Hex color for the widget primary accent."},"primaryForeground":{"type":"string","description":"Foreground color on primary."},"backgroundColor":{"type":"string","description":"Widget background color."},"foregroundColor":{"type":"string","description":"Widget text color."},"secondaryColor":{"type":"string","description":"Secondary background color."},"secondaryForeground":{"type":"string","description":"Secondary text color."},"position":{"type":"string","enum":["bottom-right","bottom-left"],"description":"Widget position on screen."},"greeting":{"type":"string","description":"Opening message shown to users."},"botName":{"type":"string","description":"Display name shown in the widget header."},"showBranding":{"type":"boolean","description":"Whether HelpBot branding is shown (Scale plan can hide)."},"aiLanguage":{"type":"string","description":"Language code (e.g. \"en\", \"ar\") or \"auto\"."},"inputPlaceholder":{"type":"string","description":"Placeholder text for the input field."},"typingText":{"type":"string","description":"Text shown while AI is generating a response."},"onlineText":{"type":"string","description":"Status indicator text."},"handoffText":{"type":"string","description":"Label for the human handoff button."},"handoffSentText":{"type":"string","description":"Confirmation message after handoff request."},"emailPlaceholder":{"type":"string","description":"Placeholder for the email input during handoff."},"emailSendText":{"type":"string","description":"Label for the send email button."},"emailSkipText":{"type":"string","description":"Label for the skip email button."},"feedbackYesText":{"type":"string","description":"Thumbs-up feedback label."},"feedbackNoText":{"type":"string","description":"Thumbs-down feedback label."},"errorText":{"type":"string","description":"Generic error message."},"networkErrorText":{"type":"string","description":"Network connectivity error message."}},"required":["primaryColor","primaryForeground","backgroundColor","foregroundColor","secondaryColor","secondaryForeground","position","greeting","botName","showBranding","aiLanguage","inputPlaceholder","typingText","onlineText","handoffText","handoffSentText","emailPlaceholder","emailSendText","emailSkipText","feedbackYesText","feedbackNoText","errorText","networkErrorText"],"additionalProperties":false,"description":"The full updated widget configuration."}},"required":["updated","config"],"additionalProperties":false}}}},"400":{"description":"No valid fields to update, or invalid field value."},"401":{"description":"Invalid API key."},"403":{"description":"Removing branding requires Scale plan."},"500":{"description":"Internal server error."}}}},"/api/v1/feedback":{"post":{"tags":["Chat"],"summary":"Submit feedback","description":"Record whether the AI answer was helpful. Used by the thumbs-up / thumbs-down buttons in the widget.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"conversationId":{"type":"string","description":"The conversation ID returned by /api/v1/chat.","example":"conv_abc123"},"helpful":{"type":"string","enum":["yes","no"],"description":"Whether the answer was helpful.","example":"yes"},"apiKey":{"description":"Your API key. Can also be passed as a Bearer token in the Authorization header.","example":"wk_live_abc123","type":"string"}},"required":["conversationId","helpful"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"success":{"type":"boolean","description":"Always true on success."}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Missing or invalid fields."},"401":{"description":"Invalid API key."},"500":{"description":"Internal server error."}}}},"/api/v1/handoff":{"post":{"tags":["Chat"],"summary":"Request human handoff","description":"Escalate a conversation to a human agent. Marks the conversation as handed off and sends an email notification to the site owner.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"conversationId":{"type":"string","description":"The conversation ID to escalate.","example":"conv_abc123"},"apiKey":{"description":"Your API key. Can also be passed as a Bearer token in the Authorization header.","example":"wk_live_abc123","type":"string"},"customerEmail":{"description":"Optional — lets the agent follow up with the customer.","example":"user@example.com","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["conversationId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"success":{"type":"boolean","description":"Always true on success."}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Missing required fields."},"401":{"description":"Invalid API key."},"500":{"description":"Internal server error."}}}},"/api/v1/sources/rescrape":{"post":{"tags":["Sources"],"summary":"Re-scrape a FAQ source","description":"Triggers a fresh scrape of an existing FAQ source by ID. The source must be a URL (not a file upload). The scrape runs asynchronously — poll GET /api/v1/sources to check status. Requires Scale plan.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"sourceId":{"type":"string","description":"The ID of the FAQ source to re-scrape.","example":"src_abc123"},"apiKey":{"description":"Your API key. Can also be passed as a Bearer token in the Authorization header.","example":"wk_live_abc123","type":"string"}},"required":["sourceId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"sourceId":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"The source ID."},"url":{"type":"string","description":"The URL being re-scraped."},"status":{"type":"string","enum":["scraping"],"description":"Always 'scraping' on success."},"message":{"type":"string","description":"Human-readable status message."}},"required":["sourceId","url","status","message"],"additionalProperties":false}}}},"400":{"description":"Missing sourceId or source is a file upload."},"401":{"description":"Invalid API key."},"403":{"description":"Plan not allowed."},"404":{"description":"Source not found or belongs to a different site."},"500":{"description":"Internal server error."}}}},"/api/v1/analytics/overview":{"get":{"tags":["Analytics"],"summary":"Get analytics overview","description":"Returns summary statistics for your site: total questions, satisfaction rate, handoff count, week-over-week trend, and credit usage. Requires Growth or Scale plan.","security":[{"bearerAuth":[]}],"parameters":[{"name":"range","in":"query","required":false,"description":"Time range filter. Defaults to \"30d\".","example":"30d","schema":{"type":"string","enum":["7d","30d","all"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"range":{"type":"string","description":"The applied time range."},"totalQuestions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total conversations in the range."},"satisfactionRate":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Percentage of feedback marked helpful (0-100)."},"helpfulCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Conversations rated helpful."},"totalFeedback":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total conversations that received feedback."},"handoffCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Conversations escalated to a human."},"handoffRate":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Handoff percentage of total questions (0-100)."},"weekOverWeekChange":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Percentage change in questions vs the previous week."},"credits":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Credits consumed this month."},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Monthly credit cap."}},"required":["used","limit"],"additionalProperties":false}},"required":["range","totalQuestions","satisfactionRate","helpfulCount","totalFeedback","handoffCount","handoffRate","weekOverWeekChange","credits"],"additionalProperties":false}}}},"401":{"description":"Invalid API key."},"403":{"description":"Plan not allowed (requires Growth or Scale)."},"500":{"description":"Internal server error."}}}},"/api/v1/analytics/activity":{"get":{"tags":["Analytics"],"summary":"Get daily activity","description":"Returns daily question counts for chart rendering. Each entry contains a date (YYYY-MM-DD) and the number of questions asked that day. Requires Growth or Scale plan.","security":[{"bearerAuth":[]}],"parameters":[{"name":"range","in":"query","required":false,"description":"Time range filter. Defaults to \"30d\".","example":"30d","schema":{"type":"string","enum":["7d","30d","all"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"range":{"type":"string","description":"The applied time range."},"activity":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Date in YYYY-MM-DD format.","example":"2026-03-15"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Number of questions on this date.","example":12}},"required":["date","count"],"additionalProperties":false},"description":"Daily question counts, sorted ascending by date."}},"required":["range","activity"],"additionalProperties":false}}}},"401":{"description":"Invalid API key."},"403":{"description":"Plan not allowed (requires Growth or Scale)."},"500":{"description":"Internal server error."}}}},"/api/v1/conversations":{"get":{"tags":["Analytics"],"summary":"List conversations","description":"Returns a paginated list of conversations with flexible filters. Use `filter=unanswered` to find gaps, `filter=handoff` for escalations, or combine with `search` to find specific topics. Requires Growth or Scale plan.","security":[{"bearerAuth":[]}],"parameters":[{"name":"range","in":"query","required":false,"description":"Time range filter. Defaults to \"30d\".","example":"30d","schema":{"type":"string","enum":["7d","30d","all"]}},{"name":"limit","in":"query","required":false,"description":"Page size (1-100). Defaults to 20.","example":"20","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"page","in":"query","required":false,"description":"Page number. Defaults to 1.","example":"1","schema":{"type":"integer","minimum":1}},{"name":"filter","in":"query","required":false,"description":"Pre-built filter. \"unanswered\" returns conversations rated unhelpful or containing fallback phrases. Defaults to \"all\".","example":"all","schema":{"type":"string","enum":["all","unanswered","helpful","unhelpful","handoff"]}},{"name":"search","in":"query","required":false,"description":"Search within question text.","schema":{"type":"string"}},{"name":"sessionId","in":"query","required":false,"description":"Filter by session ID.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort order. Defaults to \"-createdAt\" (newest first).","example":"-createdAt","schema":{"type":"string","enum":["-createdAt","createdAt"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"conversations":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Conversation ID."},"sessionId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Session identifier."},"question":{"type":"string","description":"The user's question."},"answer":{"type":"string","description":"The AI's answer."},"sources":{"type":"array","items":{"type":"string"},"description":"Source URLs used in the answer."},"wasHelpful":{"anyOf":[{"type":"string","enum":["yes","no"]},{"type":"null"}],"description":"User feedback, if any."},"handedOffToHuman":{"type":"boolean","description":"Whether escalated to a human."},"createdAt":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","sessionId","question","answer","sources","wasHelpful","handedOffToHuman","createdAt"],"additionalProperties":false},"description":"List of conversations."},"totalDocs":{"type":"number","description":"Total matching conversations."},"page":{"type":"number","description":"Current page number."},"totalPages":{"type":"number","description":"Total number of pages."},"limit":{"type":"number","description":"Page size."}},"required":["conversations","totalDocs","page","totalPages","limit"],"additionalProperties":false}}}},"401":{"description":"Invalid API key."},"403":{"description":"Plan not allowed (requires Growth or Scale)."},"500":{"description":"Internal server error."}}}},"/api/v1/webhooks":{"post":{"tags":["Webhooks"],"summary":"Create a webhook","description":"Registers a new webhook endpoint. The signing secret is returned once — store it securely. Max 5 webhooks per site. Requires Growth or Scale plan.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string","format":"uri","description":"The callback URL to receive webhook POST requests.","example":"https://example.com/webhooks/helpbot"},"events":{"minItems":1,"type":"array","items":{"type":"string","enum":["conversation.created","conversation.unanswered","conversation.feedback","conversation.handoff"]},"description":"Events to subscribe to.","example":["conversation.created","conversation.unanswered"]},"description":{"description":"Optional description for this webhook.","example":"Sync new conversations to Slack","type":"string","maxLength":200}},"required":["url","events"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"webhook":{"type":"object","properties":{"id":{"type":"string","example":"wh_abc123"},"url":{"type":"string","format":"uri","example":"https://example.com/webhooks/helpbot"},"secret":{"type":"string","description":"HMAC signing secret — only returned on creation.","example":"a1b2c3d4..."},"events":{"type":"array","items":{"type":"string"},"example":["conversation.created","conversation.unanswered"]},"isActive":{"type":"boolean","example":true},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"Sync to Slack"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","example":"2024-01-15T10:30:00Z"}},"required":["id","url","secret","events","isActive","description","createdAt"],"additionalProperties":false,"description":"The created webhook, including the secret (shown once)."}},"required":["webhook"],"additionalProperties":false}}}},"400":{"description":"Invalid request body."},"401":{"description":"Invalid API key."},"403":{"description":"Plan not allowed or webhook limit reached."},"500":{"description":"Internal server error."}}},"get":{"tags":["Webhooks"],"summary":"List webhooks","description":"Returns all webhooks for your site. Secrets are redacted to last 4 characters. Requires Growth or Scale plan.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"webhooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"wh_abc123"},"url":{"type":"string","format":"uri","example":"https://example.com/webhooks/helpbot"},"secretHint":{"type":"string","description":"Last 4 characters of the signing secret.","example":"…d4e5"},"events":{"type":"array","items":{"type":"string"},"example":["conversation.created","conversation.unanswered"]},"isActive":{"type":"boolean","example":true},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"Sync to Slack"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","example":"2024-01-15T10:30:00Z"}},"required":["id","url","secretHint","events","isActive","description","createdAt"],"additionalProperties":false},"description":"Array of webhook objects with redacted secrets."}},"required":["webhooks"],"additionalProperties":false}}}},"401":{"description":"Invalid API key."},"403":{"description":"Plan not allowed."},"500":{"description":"Internal server error."}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook","description":"Permanently removes a webhook by ID. Requires Growth or Scale plan.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"description":"The ID of the webhook to delete.","example":"wh_abc123","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"deleted":{"type":"boolean","description":"Always true on success."}},"required":["deleted"],"additionalProperties":false}}}},"400":{"description":"Missing id query parameter."},"401":{"description":"Invalid API key."},"403":{"description":"Plan not allowed."},"404":{"description":"Webhook not found or belongs to a different site."},"500":{"description":"Internal server error."}}}}}}