{"openapi":"3.1.0","info":{"title":"ASDK API","version":"0.1.0","summary":"The public API of ASDK: sites, knowledge, answers, leads and webhooks.","description":"Call it with a workspace API key as a bearer token (`Authorization: Bearer asdk_live_…`). Keys with the `read` scope read; keys with the `write` scope also make the changes marked `write`. Errors are RFC 9457 problem details (`application/problem+json`)."},"servers":[{"url":"https://api.asdk.com","description":"Production"}],"tags":[{"name":"workspaces","description":"Workspaces and their settings."},{"name":"sites","description":"The websites a workspace's agents work on."},{"name":"knowledge","description":"Knowledge sources, their documents and Q&A pairs."},{"name":"answers","description":"Server-side answers from a site's knowledge (API keys with the write scope)."},{"name":"inbox","description":"Conversations of the widget, read and reviewed in the dashboard."},{"name":"leads","description":"Contact details visitors left, their status and CSV export."},{"name":"insights","description":"Overview numbers, knowledge gaps and what visitors ask."},{"name":"search","description":"The Search agent of a site — its settings and what visitors search for."},{"name":"webhooks","description":"Workspace webhooks — signed events for leads, conversations, knowledge gaps and source syncs."}],"paths":{"/v1/workspaces/{id}":{"get":{"operationId":"getWorkspace","tags":["workspaces"],"summary":"Get a workspace","description":"Any member, or an API key of this workspace.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}]},"/v1/workspaces/{id}/sites":{"get":{"operationId":"listSites","tags":["sites"],"summary":"List the workspace's sites","description":"Every site with a summary of its knowledge, and the plan's site and page limits.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Sites, oldest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}]},"/v1/sites/{siteId}":{"get":{"operationId":"getSite","tags":["sites"],"summary":"A site","security":[{"apiKey":[]}],"responses":{"200":{"description":"The site.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/SiteId"}]},"/v1/sites/{siteId}/sources":{"get":{"operationId":"listSources","tags":["knowledge"],"summary":"List a site's knowledge sources","description":"Sources, oldest first, including the site's Q&A source once it has pairs. Text snippet bodies are left out; read one source for its body.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The sources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/SiteId"}]},"/v1/sources/{sourceId}":{"get":{"operationId":"getSource","tags":["knowledge"],"summary":"A knowledge source","description":"Status and progress of the last or running sync; poll every few seconds while `syncing`.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Source"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/SourceId"}]},"/v1/sources/{sourceId}/sync":{"post":{"operationId":"syncSource","tags":["knowledge"],"summary":"Sync a source now","description":"Reads the source again; unchanged pages are not embedded again. A request during a sync runs another sync after it.","security":[{"apiKey":["write"]}],"responses":{"202":{"description":"The sync is queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Source"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/KnowledgeConflict"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/SourceId"}]},"/v1/sources/{sourceId}/documents":{"get":{"operationId":"listDocuments","tags":["knowledge"],"summary":"List a source's documents","description":"Ordered by URL, a page at a time; `q` searches URL and title.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Search"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/PageLimit"},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/DocumentStatus"}}],"responses":{"200":{"description":"A page of documents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentList"}}}},"400":{"$ref":"#/components/responses/ValidationProblem"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/SourceId"}]},"/v1/sites/{siteId}/qa":{"get":{"operationId":"listQaPairs","tags":["knowledge"],"summary":"List a site's Q&A pairs","description":"Newest first, a page at a time; `q` searches questions and answers.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Search"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/PageLimit"}],"responses":{"200":{"description":"A page of Q&A pairs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QaPairList"}}}},"400":{"$ref":"#/components/responses/ValidationProblem"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"post":{"operationId":"createQaPair","tags":["knowledge"],"summary":"Add a Q&A pair","description":"Each pair is embedded as its own vector (`kind` qa), which the answer engine prefers on ties.","security":[{"apiKey":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QaPairInput"}}}},"responses":{"201":{"description":"The new pair, being embedded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QaPair"}}}},"400":{"$ref":"#/components/responses/ValidationProblem"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/KnowledgeConflict"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/SiteId"}]},"/v1/workspaces/{id}/overview":{"get":{"operationId":"getOverview","tags":["insights"],"summary":"Overview of the workspace","description":"Any member or an API key. Conversations, answers, grounded rate,\nleads and ratings of the last `days` days (whole days in the\nworkspace's time zone, today included) per day and per site, the\nsame numbers for the period before, the pages chats start on, and\nthe number of open knowledge gaps.\n","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/StatsSiteId"},{"$ref":"#/components/parameters/StatsDays"}],"responses":{"200":{"description":"The overview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Overview"}}}},"400":{"$ref":"#/components/responses/ValidationProblem"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}]},"/v1/workspaces/{id}/conversations":{"get":{"operationId":"listConversations","tags":["inbox"],"summary":"List conversations","description":"Any member or an API key. Conversations with at least one message,\nlatest activity first, a page at a time. `q` searches message texts\nand the lead's email and name.\n","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/StatsSiteId"},{"name":"agent","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ConversationAgent"}},{"name":"unanswered","in":"query","required":false,"description":"Only conversations with an answer that was not grounded in the site's content.","schema":{"type":"boolean"}},{"name":"withLead","in":"query","required":false,"description":"Only conversations where the visitor left contact details.","schema":{"type":"boolean"}},{"name":"unreviewed","in":"query","required":false,"description":"Only conversations nobody marked reviewed.","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/PreviewsFilter"},{"$ref":"#/components/parameters/Search"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/PageLimit"}],"responses":{"200":{"description":"A page of conversations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationList"}}}},"400":{"$ref":"#/components/responses/ValidationProblem"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}]},"/v1/workspaces/{id}/conversations/{conversationId}":{"get":{"operationId":"getConversation","tags":["inbox"],"summary":"A conversation","description":"Any member or an API key. Every message with its sources and the visitor's rating, the visitor, and the leads left in it.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"$ref":"#/components/parameters/InboxConversationId"}]},"/v1/workspaces/{id}/leads":{"get":{"operationId":"listLeads","tags":["leads"],"summary":"List leads","description":"Any member or an API key. Newest first, a page at a time, with the\nnumber of leads per status under the same filters. `q` searches\nemail, name, company and note.\n","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/StatsSiteId"},{"$ref":"#/components/parameters/LeadStatusFilter"},{"$ref":"#/components/parameters/PreviewsFilter"},{"$ref":"#/components/parameters/Search"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/PageLimit"}],"responses":{"200":{"description":"A page of leads.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadList"}}}},"400":{"$ref":"#/components/responses/ValidationProblem"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}]},"/v1/workspaces/{id}/leads/export":{"get":{"operationId":"exportLeads","tags":["leads"],"summary":"Export leads as CSV","description":"Any member or an API key. The leads matching the filters, newest\nfirst, at most 50,000: UTF-8 with a byte order mark, RFC 4180\nquoting, and every cell that starts with =, +, -, @, a tab or a\ncarriage return prefixed with an apostrophe so spreadsheets never\nrun it as a formula.\n","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/StatsSiteId"},{"$ref":"#/components/parameters/LeadStatusFilter"},{"$ref":"#/components/parameters/PreviewsFilter"},{"$ref":"#/components/parameters/Search"}],"responses":{"200":{"description":"The CSV file.","headers":{"Content-Disposition":{"description":"attachment; filename=\"leads-….csv\"","schema":{"type":"string"}}},"content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/ValidationProblem"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}]},"/v1/workspaces/{id}/leads/{leadId}":{"get":{"operationId":"getLead","tags":["leads"],"summary":"A lead","description":"Any member or an API key. The lead with the conversation it was left in.","security":[{"apiKey":[]}],"responses":{"200":{"description":"The lead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"patch":{"operationId":"updateLead","tags":["leads"],"summary":"Change a lead's status","description":"Any member.","security":[{"apiKey":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadUpdate"}}}},"responses":{"200":{"description":"The lead after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadDetail"}}}},"400":{"$ref":"#/components/responses/ValidationProblem"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"$ref":"#/components/parameters/LeadId"}]},"/v1/workspaces/{id}/insights":{"get":{"operationId":"getInsights","tags":["insights"],"summary":"What visitors ask","description":"Any member or an API key. The questions visitors ask most (grouped\nby normalized text), the pages answers cite and the answers visitors\nrated down, over the last `days` days. These lists need a plan with\nthe catalog feature `insights-report`; without it `entitled` is\nfalse, the lists are empty and `minPlan` names the plan to upgrade\nto. Knowledge gaps are in every plan (`/gaps`).\n","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/StatsSiteId"},{"$ref":"#/components/parameters/StatsDays"}],"responses":{"200":{"description":"The insights.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Insights"}}}},"400":{"$ref":"#/components/responses/ValidationProblem"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}]},"/v1/workspaces/{id}/gaps":{"get":{"operationId":"listKnowledgeGaps","tags":["insights"],"summary":"List open knowledge gaps","description":"Any member or an API key. Questions the knowledge base could not answer, most asked first, a page at a time.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/StatsSiteId"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/PageLimit"}],"responses":{"200":{"description":"A page of open gaps.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeGapList"}}}},"400":{"$ref":"#/components/responses/ValidationProblem"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}]},"/v1/sites/{siteId}/search/analytics":{"get":{"operationId":"getSearchAnalytics","tags":["search"],"summary":"What visitors search for","description":"Any member, or a workspace API key. Searches visitors settled on in\nthe last `days` days (UTC, today included): totals with the\nclick-through rate (clicked searches among those with results),\nevery day of the period, the top searches, and the searches that\nfound nothing useful — no result or only weak ones, and no answer —\nthat were not answered since.\n","security":[{"apiKey":[]}],"parameters":[{"name":"days","in":"query","required":false,"description":"Length of the period in days (default 30).","schema":{"type":"integer","minimum":1,"maximum":365}},{"name":"limit","in":"query","required":false,"description":"Rows per query list (default 20).","schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"The analytics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchAnalytics"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/SiteId"}]},"/v1/sites/{siteId}/ask":{"post":{"operationId":"askSite","tags":["answers"],"summary":"Answer a question from a site's knowledge","description":"Answers a question server-side exactly as the site's chat widget\nwould: the same knowledge base, the same grounding and citations.\n`grounded` is false when the knowledge base did not cover the\nquestion (the question is then recorded as a knowledge gap).\n\nNeeds a person (any member) or an API key with the **write** scope,\nand API access in the workspace's plan (\"not-in-plan\" otherwise).\nWhile the catalog lists API access as coming soon, every workspace\ngets 403 \"coming-soon\".\nEvery answer counts toward the plan's monthly answers; past the hard\ncap (110 % of the limit) the request answers `429` with type\n\"answer-limit-reached\" until the next month. Conversations are not\nstored.\n","security":[{"apiKey":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"}}}},"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskAnswer"}}}},"400":{"$ref":"#/components/responses/ValidationProblem"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"},"504":{"$ref":"#/components/responses/AnswerTimeout"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/SiteId"}]},"/v1/workspaces/{id}/webhooks":{"get":{"operationId":"listWebhookEndpoints","tags":["webhooks"],"summary":"List webhook endpoints","description":"Owners, admins and API keys. The workspace's endpoints, the events\nthey can subscribe to, and whether the plan includes webhooks\n(`entitled`; without them endpoints are kept but receive nothing).\n","security":[{"apiKey":[]}],"responses":{"200":{"description":"The endpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"post":{"operationId":"createWebhookEndpoint","tags":["webhooks"],"summary":"Add a webhook endpoint","description":"Owners, admins and API keys with the write scope (Zapier- and\nMake-style subscriptions). The answer carries the signing secret,\nshown this once. At most 10 endpoints per workspace\n(`limit-reached`); the plan must include webhooks (`not-in-plan`).\nThe address must be public https.\n","security":[{"apiKey":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointInput"}}}},"responses":{"201":{"description":"The endpoint and its secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedWebhookEndpoint"}}}},"400":{"$ref":"#/components/responses/ValidationProblem"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}]},"/v1/workspaces/{id}/webhooks/{webhookId}":{"patch":{"operationId":"updateWebhookEndpoint","tags":["webhooks"],"summary":"Change a webhook endpoint","description":"Owners, admins and API keys with the write scope. Switching an\nendpoint on (`enabled: true`) also clears a stop after repeated\nfailures.\n","security":[{"apiKey":["write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointPatch"}}}},"responses":{"200":{"description":"The endpoint after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"$ref":"#/components/responses/ValidationProblem"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"delete":{"operationId":"deleteWebhookEndpoint","tags":["webhooks"],"summary":"Remove a webhook endpoint","description":"Owners, admins and API keys with the write scope. Its delivery log goes with it.","security":[{"apiKey":["write"]}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"$ref":"#/components/parameters/WebhookEndpointId"}]},"/v1/workspaces/{id}/webhooks/{webhookId}/test":{"post":{"operationId":"testWebhookEndpoint","tags":["webhooks"],"summary":"Send a test event","description":"Owners, admins and API keys with the write scope. Sends a signed\n`test` event now (one attempt, also to a switched-off endpoint) and\nanswers with the logged delivery: the status the endpoint answered,\nthe start of its answer and how long it took. The plan must include\nwebhooks (`not-in-plan`).\n","security":[{"apiKey":["write"]}],"responses":{"200":{"description":"The delivery of the test event.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"$ref":"#/components/parameters/WebhookEndpointId"}]},"/v1/workspaces/{id}/webhooks/{webhookId}/deliveries":{"get":{"operationId":"listWebhookDeliveries","tags":["webhooks"],"summary":"An endpoint's delivery log","description":"Owners, admins and API keys. Newest first, a page at a time, kept 30 days, with each delivery's payload.","security":[{"apiKey":[]}],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/WebhookDeliveryLimit"}],"responses":{"200":{"description":"A page of deliveries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}}},"400":{"$ref":"#/components/responses/ValidationProblem"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"$ref":"#/components/parameters/WebhookEndpointId"}]},"/v1/workspaces/{id}/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver":{"post":{"operationId":"redeliverWebhook","tags":["webhooks"],"summary":"Send a delivery's event again","description":"Owners, admins and API keys with the write scope. One attempt now, logged as a new delivery of the same event (same body, new signature). The plan must include webhooks (`not-in-plan`).","security":[{"apiKey":["write"]}],"responses":{"200":{"description":"The new delivery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"},{"$ref":"#/components/parameters/WebhookEndpointId"},{"$ref":"#/components/parameters/WebhookDeliveryId"}]},"/v1/workspaces/{id}/suspension":{"get":{"operationId":"getWorkspaceSuspension","tags":["workspaces"],"summary":"Whether ASDK suspended the workspace","description":"Any member (and the workspace's API keys). A suspended workspace's\nwidgets are unavailable and its dashboard is read-only: writes answer\n403 (response `WorkspaceSuspended`). The dashboard shows a banner from this.\n","security":[{"apiKey":[]}],"responses":{"200":{"description":"The workspace's suspension.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceSuspension"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/Problem"}}},"parameters":[{"$ref":"#/components/parameters/WorkspaceId"}]}},"x-webhooks":{"lead.created":{"post":{"operationId":"onLeadCreated","tags":["webhooks"],"summary":"A visitor left their contact details","description":"Sent for every new lead (chat, forms, WebMCP). `lead.preview` marks leads from the dashboard's preview.","parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookEventHeader"},{"$ref":"#/components/parameters/WebhookDeliveryHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadWebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery."}}}},"lead.updated":{"post":{"operationId":"onLeadUpdated","tags":["webhooks"],"summary":"A lead's details, status or qualification changed","description":"`data.changes` names the changed fields (email, name, company, phone, note, status, qualifiedAt) and `data.previous` their earlier values. Score-only changes are not sent.","parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookEventHeader"},{"$ref":"#/components/parameters/WebhookDeliveryHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadWebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery."}}}},"conversation.closed":{"post":{"operationId":"onConversationClosed","tags":["webhooks"],"summary":"A conversation went quiet","description":"Sent when a conversation had no new message for 30 minutes, with its transcript (the latest 100 messages). A visitor who returns and goes quiet again closes it again.","parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookEventHeader"},{"$ref":"#/components/parameters/WebhookDeliveryHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationClosedWebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery."}}}},"knowledge_gap.created":{"post":{"operationId":"onKnowledgeGapCreated","tags":["webhooks"],"summary":"Visitors asked something the knowledge base could not answer","description":"Sent the first time a question goes unanswered (repeats count up the same gap).","parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookEventHeader"},{"$ref":"#/components/parameters/WebhookDeliveryHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeGapWebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery."}}}},"source.synced":{"post":{"operationId":"onSourceSynced","tags":["webhooks"],"summary":"A knowledge source finished syncing","description":"`data.source.status` is `ready` after a successful sync and `error` after a failed one (with `error`).","parameters":[{"$ref":"#/components/parameters/WebhookSignature"},{"$ref":"#/components/parameters/WebhookEventHeader"},{"$ref":"#/components/parameters/WebhookDeliveryHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceSyncedWebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx confirms the delivery."}}}}},"components":{"schemas":{"AskAnswer":{"type":"object","additionalProperties":false,"required":["answer","sources","grounded"],"properties":{"answer":{"type":"string","description":"The answer as Markdown, in the question's language."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/AskSource"},"description":"The pages the answer cites."},"grounded":{"type":"boolean","description":"False when the knowledge base did not cover the question."},"language":{"type":"string","description":"Base code of the answer's language (`en`)."}}},"AskRequest":{"type":"object","additionalProperties":false,"required":["question"],"properties":{"question":{"type":"string","minLength":1,"maxLength":2000,"description":"The question, as a visitor would ask it."},"locale":{"type":"string","maxLength":35,"description":"BCP 47 language for short questions whose language cannot be told (e.g. `de`)."}}},"AskSource":{"type":"object","additionalProperties":false,"required":["title","url"],"properties":{"title":{"type":"string"},"url":{"type":"string"}}},"CitedPage":{"type":"object","additionalProperties":false,"required":["url","title","answers"],"properties":{"url":{"type":"string"},"title":{"type":"string"},"answers":{"type":"integer"}}},"ConversationAgent":{"type":"string","enum":["chat","sales","search","forms","voice"]},"ConversationClosedWebhookEvent":{"type":"object","required":["id","type","createdAt","workspaceId","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["conversation.closed"]},"createdAt":{"type":"string","format":"date-time"},"workspaceId":{"type":"string"},"data":{"type":"object","required":["site","conversation"],"properties":{"site":{"$ref":"#/components/schemas/WebhookSite"},"conversation":{"type":"object","required":["id","siteId","visitorId","agent","pageUrl","leadId","startedAt","lastMessageAt","messageCount","preview","messages","messagesTruncated"],"properties":{"id":{"type":"string"},"siteId":{"type":"string"},"visitorId":{"type":"string"},"agent":{"type":"string"},"pageUrl":{"type":["string","null"]},"leadId":{"type":["string","null"]},"startedAt":{"type":"string","format":"date-time"},"lastMessageAt":{"type":"string","format":"date-time"},"messageCount":{"type":"integer"},"preview":{"type":"boolean"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/WebhookMessage"}},"messagesTruncated":{"type":"boolean","description":"Only the latest 100 messages are sent."},"dashboardUrl":{"type":"string"}}}}}}},"ConversationDetail":{"type":"object","additionalProperties":false,"required":["id","siteId","siteName","siteOrigin","agent","startedAt","lastMessageAt","preview","unanswered","visitor","messages","leads"],"properties":{"id":{"type":"string"},"siteId":{"type":"string"},"siteName":{"type":"string"},"siteOrigin":{"type":"string"},"agent":{"$ref":"#/components/schemas/ConversationAgent"},"pageUrl":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"lastMessageAt":{"type":"string","format":"date-time"},"preview":{"type":"boolean"},"unanswered":{"type":"boolean"},"reviewedAt":{"type":"string","format":"date-time"},"reviewedBy":{"$ref":"#/components/schemas/PersonRef"},"visitor":{"$ref":"#/components/schemas/InboxVisitor"},"messages":{"type":"array","description":"Oldest first, at most 1,000.","items":{"$ref":"#/components/schemas/InboxMessage"}},"leads":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}}}},"ConversationList":{"type":"object","additionalProperties":false,"required":["conversations"],"properties":{"conversations":{"type":"array","items":{"$ref":"#/components/schemas/ConversationSummary"}},"nextCursor":{"type":"string"}}},"ConversationSummary":{"type":"object","additionalProperties":false,"required":["id","siteId","siteName","siteOrigin","agent","startedAt","lastMessageAt","preview","messages","questions","unanswered","thumbsUp","thumbsDown","firstQuestion","lastMessage","lastMessageRole"],"properties":{"id":{"type":"string","examples":["conv_6Tr1Kp9Zm2Lx8Qw4Nb7C"]},"siteId":{"type":"string"},"siteName":{"type":"string"},"siteOrigin":{"type":"string"},"agent":{"$ref":"#/components/schemas/ConversationAgent"},"pageUrl":{"type":"string","description":"The page the conversation started on."},"startedAt":{"type":"string","format":"date-time"},"lastMessageAt":{"type":"string","format":"date-time"},"reviewedAt":{"type":"string","format":"date-time"},"preview":{"type":"boolean","description":"Started in the dashboard's preview, not by a visitor."},"lead":{"$ref":"#/components/schemas/LeadRef"},"messages":{"type":"integer"},"questions":{"type":"integer"},"unanswered":{"type":"boolean","description":"An answer was not grounded in the site's content."},"thumbsUp":{"type":"integer"},"thumbsDown":{"type":"integer"},"firstQuestion":{"type":"string","description":"The visitor's first message, shortened to 200 characters."},"lastMessage":{"type":"string","description":"The last message, shortened to 200 characters."},"lastMessageRole":{"type":"string","enum":["visitor","agent"]}}},"CreatedWebhookEndpoint":{"type":"object","additionalProperties":false,"required":["endpoint","secret"],"properties":{"endpoint":{"$ref":"#/components/schemas/WebhookEndpoint"},"secret":{"type":"string","description":"The signing secret (`whsec_…`). Shown once; store it now."}}},"Document":{"type":"object","additionalProperties":false,"required":["id","sourceId","siteId","url","title","status","chunkCount","updatedAt"],"properties":{"id":{"type":"string","examples":["doc_2Hq7Lm9Xc4Tz8Pw1Nb6V"]},"sourceId":{"type":"string"},"siteId":{"type":"string"},"url":{"type":"string","description":"The page address, or the file name of an upload."},"title":{"type":"string"},"status":{"$ref":"#/components/schemas/DocumentStatus"},"chunkCount":{"type":"integer"},"language":{"type":"string","description":"ISO 639-1 code, when detected."},"error":{"type":"string","description":"Why the page is skipped or failed, in words for people."},"indexedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"DocumentList":{"type":"object","additionalProperties":false,"required":["documents","total"],"properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"total":{"type":"integer","description":"Documents matching the filters."},"nextCursor":{"type":"string","description":"Present when there are more."}}},"DocumentStatus":{"type":"string","enum":["pending","indexed","skipped","excluded","error"]},"DownvotedAnswer":{"type":"object","additionalProperties":false,"required":["messageId","conversationId","siteId","siteName","question","answer","ratedAt"],"properties":{"messageId":{"type":"string"},"conversationId":{"type":"string"},"siteId":{"type":"string"},"siteName":{"type":"string"},"question":{"type":"string"},"answer":{"type":"string"},"comment":{"type":"string"},"ratedAt":{"type":"string","format":"date-time"}}},"InboxMessage":{"type":"object","additionalProperties":false,"required":["id","role","text","createdAt","sources","refusal"],"properties":{"id":{"type":"string"},"role":{"type":"string","enum":["visitor","agent"]},"text":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/InboxSource"}},"grounded":{"type":"boolean","description":"Agent answers that went through retrieval; absent for greetings."},"refusal":{"type":"boolean","description":"The agent said it does not know."},"rating":{"type":"string","enum":["up","down"]},"ratingComment":{"type":"string"}}},"InboxSource":{"type":"object","additionalProperties":false,"required":["title","url"],"properties":{"title":{"type":"string"},"url":{"type":"string"}}},"InboxVisitor":{"type":"object","additionalProperties":false,"required":["id","otherConversations"],"properties":{"id":{"type":"string"},"email":{"type":"string","description":"From the site's identify call, when it made one."},"name":{"type":"string"},"firstSeenAt":{"type":"string","format":"date-time"},"otherConversations":{"type":"integer"}}},"Insights":{"type":"object","additionalProperties":false,"required":["timezone","from","to","days","openGaps","entitled","minPlan","topQuestions","citedPages","downvoted"],"properties":{"timezone":{"type":"string"},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"days":{"type":"integer"},"openGaps":{"type":"integer"},"entitled":{"type":"boolean","description":"The plan includes \"What visitors ask\" insights (catalog feature insights-report)."},"minPlan":{"$ref":"#/components/schemas/PlanRef"},"topQuestions":{"type":"array","items":{"$ref":"#/components/schemas/TopQuestion"}},"citedPages":{"type":"array","items":{"$ref":"#/components/schemas/CitedPage"}},"downvoted":{"type":"array","items":{"$ref":"#/components/schemas/DownvotedAnswer"}}}},"KnowledgeGap":{"type":"object","additionalProperties":false,"required":["id","siteId","siteName","question","count","firstSeenAt","lastSeenAt"],"properties":{"id":{"type":"string","description":"The hex SHA-256 of the normalized question."},"siteId":{"type":"string"},"siteName":{"type":"string"},"question":{"type":"string"},"count":{"type":"integer","description":"How often visitors asked it."},"firstSeenAt":{"type":"string","format":"date-time"},"lastSeenAt":{"type":"string","format":"date-time"}}},"KnowledgeGapList":{"type":"object","additionalProperties":false,"required":["gaps","total"],"properties":{"gaps":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeGap"}},"total":{"type":"integer"},"nextCursor":{"type":"string"}}},"KnowledgeGapWebhookEvent":{"type":"object","required":["id","type","createdAt","workspaceId","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["knowledge_gap.created"]},"createdAt":{"type":"string","format":"date-time"},"workspaceId":{"type":"string"},"data":{"type":"object","required":["site","gap"],"properties":{"site":{"$ref":"#/components/schemas/WebhookSite"},"gap":{"type":"object","required":["id","siteId","question","count","firstSeenAt","lastSeenAt"],"properties":{"id":{"type":"string","description":"The gap's id for POST /v1/sites/{siteId}/gaps/{gapId}/answer."},"siteId":{"type":"string"},"question":{"type":"string"},"count":{"type":"integer"},"firstSeenAt":{"type":"string","format":"date-time"},"lastSeenAt":{"type":"string","format":"date-time"},"dashboardUrl":{"type":"string"}}}}}}},"KnowledgeStatus":{"type":"string","enum":["empty","pending","syncing","ready","error"],"description":"The site's knowledge as a whole: `syncing` while any source syncs, `error` when one failed, `empty` without sources."},"KnowledgeSummary":{"type":"object","additionalProperties":false,"required":["status","sources","documents","chunks","qaPairs"],"properties":{"status":{"$ref":"#/components/schemas/KnowledgeStatus"},"sources":{"type":"integer","description":"Sources other than the Q&A source."},"documents":{"type":"integer","description":"Indexed documents (pages, files, snippets)."},"chunks":{"type":"integer"},"qaPairs":{"type":"integer"},"lastSyncedAt":{"type":"string","format":"date-time"}}},"Lead":{"type":"object","additionalProperties":false,"required":["id","siteId","siteName","siteOrigin","email","consent","status","preview","createdAt"],"properties":{"id":{"type":"string","examples":["lead_6Tr1Kp9Zm2Lx8Qw4Nb7C"]},"siteId":{"type":"string"},"siteName":{"type":"string"},"siteOrigin":{"type":"string"},"conversationId":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"company":{"type":"string"},"phone":{"type":"string"},"note":{"type":"string"},"consent":{"type":"boolean"},"pageUrl":{"type":"string"},"status":{"$ref":"#/components/schemas/LeadStatus"},"preview":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"statusChangedAt":{"type":"string","format":"date-time"}}},"LeadCounts":{"type":"object","additionalProperties":false,"required":["new","contacted","archived"],"properties":{"new":{"type":"integer"},"contacted":{"type":"integer"},"archived":{"type":"integer"}}},"LeadDetail":{"type":"object","additionalProperties":false,"required":["lead"],"properties":{"lead":{"$ref":"#/components/schemas/Lead"},"statusChangedBy":{"$ref":"#/components/schemas/PersonRef"},"conversation":{"$ref":"#/components/schemas/ConversationDetail"}}},"LeadList":{"type":"object","additionalProperties":false,"required":["leads","counts"],"properties":{"leads":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"counts":{"$ref":"#/components/schemas/LeadCounts"},"nextCursor":{"type":"string"}}},"LeadRef":{"type":"object","additionalProperties":false,"required":["id","email","status"],"properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/LeadStatus"}}},"LeadStatus":{"type":"string","enum":["new","contacted","archived"]},"LeadUpdate":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"$ref":"#/components/schemas/LeadStatus"}}},"LeadWebhookEvent":{"type":"object","required":["id","type","createdAt","workspaceId","data"],"properties":{"id":{"type":"string","examples":["evt_2Hq7Lm9Xc4Tz8Pw1Nb6V"]},"type":{"type":"string","enum":["lead.created","lead.updated"]},"createdAt":{"type":"string","format":"date-time"},"workspaceId":{"type":"string"},"data":{"type":"object","required":["site","lead"],"properties":{"site":{"$ref":"#/components/schemas/WebhookSite"},"lead":{"$ref":"#/components/schemas/WebhookLead"},"changes":{"type":"array","items":{"type":"string"},"description":"lead.updated only."},"previous":{"type":"object","additionalProperties":true,"description":"lead.updated only; the changed fields' earlier values."}}}}},"LimitUsage":{"type":"object","additionalProperties":false,"required":["used","limit"],"properties":{"used":{"type":"integer"},"limit":{"type":"integer"}}},"Overview":{"type":"object","additionalProperties":false,"required":["timezone","from","to","days","totals","previous","series","sites","topPages","openGaps","hasConversations","installed"],"properties":{"timezone":{"type":"string","examples":["Europe/Berlin"]},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time","description":"End of today in the time zone (exclusive)."},"days":{"type":"integer"},"totals":{"$ref":"#/components/schemas/StatsTotals"},"previous":{"$ref":"#/components/schemas/StatsTotals"},"series":{"type":"array","description":"One entry per day of the period, oldest first.","items":{"$ref":"#/components/schemas/OverviewDay"}},"sites":{"type":"array","items":{"$ref":"#/components/schemas/OverviewSite"}},"topPages":{"type":"array","description":"Pages visitors' conversations started on, most first (query strings dropped).","items":{"$ref":"#/components/schemas/PageCount"}},"openGaps":{"type":"integer"},"hasConversations":{"type":"boolean","description":"Visitors ever talked to an agent of the workspace (or the site)."},"installed":{"type":"boolean","description":"A site has a verified installation."}}},"OverviewDay":{"type":"object","additionalProperties":false,"required":["date","totals"],"properties":{"date":{"type":"string","format":"date","description":"The day in the workspace's time zone."},"totals":{"$ref":"#/components/schemas/StatsTotals"}}},"OverviewSite":{"type":"object","additionalProperties":false,"required":["siteId","name","origin","totals"],"properties":{"siteId":{"type":"string"},"name":{"type":"string"},"origin":{"type":"string"},"installedAt":{"type":"string","format":"date-time"},"totals":{"$ref":"#/components/schemas/StatsTotals"}}},"PageCount":{"type":"object","additionalProperties":false,"required":["url","conversations"],"properties":{"url":{"type":"string"},"conversations":{"type":"integer"}}},"PersonRef":{"type":"object","additionalProperties":false,"required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string"}}},"PlanRef":{"type":"object","additionalProperties":false,"required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"PlanUsage":{"type":"object","additionalProperties":false,"required":["planId","sites","pages"],"properties":{"planId":{"type":"string"},"trial":{"type":"boolean","description":"The limits are a running trial's (P20)."},"sites":{"$ref":"#/components/schemas/LimitUsage"},"pages":{"$ref":"#/components/schemas/LimitUsage"}}},"Problem":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URI reference identifying the problem type; \"about:blank\" for plain HTTP errors.","examples":["about:blank"]},"title":{"type":"string","description":"Short, human-readable summary of the problem type.","examples":["Not Found"]},"status":{"type":"integer","description":"HTTP status code.","examples":[404]},"detail":{"type":"string","description":"Human-readable explanation of this occurrence."},"instance":{"type":"string","description":"Request path the problem occurred on."},"request_id":{"type":"string","description":"Request id, also returned in the X-Request-ID header."},"trace_id":{"type":"string","description":"W3C trace id of the request, also returned in the X-Trace-Id header (the id to look the request up by in the tracing backend)."},"field":{"type":"string","description":"For type \"validation\", the request field that is invalid."}}},"QaPair":{"type":"object","additionalProperties":false,"required":["id","siteId","question","answer","status","createdAt","updatedAt"],"properties":{"id":{"type":"string","examples":["qa_6Tr1Kp9Zm2Lx8Qw4Nb7C"]},"siteId":{"type":"string"},"question":{"type":"string"},"answer":{"type":"string"},"status":{"$ref":"#/components/schemas/QaPairStatus"},"error":{"type":"string"},"createdBy":{"$ref":"#/components/schemas/PersonRef"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"QaPairInput":{"type":"object","additionalProperties":false,"required":["question","answer"],"properties":{"question":{"type":"string","maxLength":1000},"answer":{"type":"string","maxLength":8000}}},"QaPairList":{"type":"object","additionalProperties":false,"required":["qaPairs","total"],"properties":{"qaPairs":{"type":"array","items":{"$ref":"#/components/schemas/QaPair"}},"total":{"type":"integer"},"nextCursor":{"type":"string"}}},"QaPairStatus":{"type":"string","enum":["pending","indexed","error"]},"Role":{"type":"string","enum":["owner","admin","member","client"],"description":"A person's role in a workspace. `client` (P29) is a client user of an\nagency: they see only their client's sites, inbox, leads and reports.\n"},"SearchAnalytics":{"type":"object","additionalProperties":false,"required":["siteId","from","to","days","totals","daily","topSearches","missedSearches"],"properties":{"siteId":{"type":"string"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"days":{"type":"integer"},"totals":{"$ref":"#/components/schemas/SearchTotals"},"daily":{"type":"array","items":{"$ref":"#/components/schemas/SearchDay"}},"topSearches":{"type":"array","items":{"$ref":"#/components/schemas/SearchQueryStat"}},"missedSearches":{"type":"array","description":"Searches without a useful result (no result or only weak ones, no answer) that are not resolved.","items":{"$ref":"#/components/schemas/SearchQueryStat"}}}},"SearchDay":{"allOf":[{"$ref":"#/components/schemas/SearchTotals"},{"type":"object","required":["day"],"properties":{"day":{"type":"string","format":"date"}}}]},"SearchQueryStat":{"type":"object","additionalProperties":false,"required":["id","query","searches","zeroResults","lowScore","answers","clicks","clickThroughRate","lastSeenAt"],"properties":{"id":{"type":"string"},"query":{"type":"string","description":"The query as a visitor last typed it."},"searches":{"type":"integer"},"zeroResults":{"type":"integer"},"lowScore":{"type":"integer"},"answers":{"type":"integer"},"clicks":{"type":"integer"},"clickThroughRate":{"type":"number"},"lastSeenAt":{"type":"string","format":"date-time"},"lastMissAt":{"type":"string","format":"date-time","description":"The last search of it that found nothing useful."}}},"SearchTotals":{"type":"object","additionalProperties":false,"required":["searches","zeroResults","lowScore","answers","clicks","clickThroughRate"],"properties":{"searches":{"type":"integer","description":"Searches visitors settled on."},"zeroResults":{"type":"integer","description":"Of them without any result and without an answer."},"lowScore":{"type":"integer","description":"Of them with only weak results and without an answer."},"answers":{"type":"integer","description":"Of them with an answer shown."},"clicks":{"type":"integer","description":"Of them with a result clicked."},"clickThroughRate":{"type":"number","description":"clicks / (searches − zeroResults), 0–1; 0 without searches with results."}}},"Site":{"type":"object","additionalProperties":false,"required":["id","workspaceId","name","origin","allowedOrigins","status","createdAt","updatedAt","knowledge"],"properties":{"id":{"type":"string","examples":["site_4Jx9TqL2mPv8Rk1sWb7Z"]},"workspaceId":{"type":"string"},"name":{"type":"string"},"origin":{"type":"string","description":"Normalized `scheme://host[:port]`.","examples":["https://example.com"]},"allowedOrigins":{"type":"array","description":"Origins whose pages may load the widget (`https://*.example.com` covers subdomains).","items":{"type":"string"}},"status":{"$ref":"#/components/schemas/SiteStatus"},"installVerifiedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"knowledge":{"$ref":"#/components/schemas/KnowledgeSummary"}}},"SiteList":{"type":"object","additionalProperties":false,"required":["sites","usage"],"properties":{"sites":{"type":"array","items":{"$ref":"#/components/schemas/Site"}},"usage":{"$ref":"#/components/schemas/PlanUsage"}}},"SiteStatus":{"type":"string","enum":["active","paused"],"description":"A paused site's widget is off and its sources are not re-synced."},"Source":{"type":"object","additionalProperties":false,"required":["id","siteId","kind","title","status","config","stats","createdAt","updatedAt"],"properties":{"id":{"type":"string","examples":["src_8fK2nQ7xLm3Pz9Tb4Wv1"]},"siteId":{"type":"string"},"kind":{"$ref":"#/components/schemas/SourceKind"},"title":{"type":"string","description":"What to call the source in a list (an address, a file name, a snippet title)."},"status":{"$ref":"#/components/schemas/SourceStatus"},"config":{"$ref":"#/components/schemas/SourceConfig"},"stats":{"$ref":"#/components/schemas/SourceStats"},"error":{"type":"string","description":"Why the last sync failed or stopped early, in words for people."},"lastSyncedAt":{"type":"string","format":"date-time"},"nextSyncAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"SourceConfig":{"type":"object","additionalProperties":false,"description":"The fields of the source's kind.","properties":{"url":{"type":"string","description":"crawl — where reading starts; pages under its path are read."},"include":{"type":"array","description":"crawl — only pages matching one of these path patterns.","items":{"type":"string"}},"exclude":{"type":"array","description":"crawl and sitemap — pages matching these path patterns are skipped.","items":{"type":"string"}},"maxPages":{"type":"integer","description":"crawl and sitemap — at most this many pages (never more than the plan allows)."},"sitemapUrl":{"type":"string","description":"sitemap — the sitemap or sitemap index."},"fileName":{"type":"string","description":"file — the uploaded file's name."},"fileSize":{"type":"integer","description":"file — size in bytes."},"contentType":{"type":"string","description":"file — media type."},"title":{"type":"string","description":"text — the snippet's title."},"body":{"type":"string","description":"text — the snippet (only when one source is read)."}}},"SourceKind":{"type":"string","enum":["crawl","sitemap","file","qa","text"]},"SourceList":{"type":"object","additionalProperties":false,"required":["sources"],"properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}},"SourceStats":{"type":"object","additionalProperties":false,"required":["found","indexed","unchanged","skipped","failed","removed","chunks"],"description":"Counters of the last or running sync.","properties":{"found":{"type":"integer","description":"Pages read so far."},"indexed":{"type":"integer","description":"Pages in the knowledge base after the sync (unchanged ones included)."},"unchanged":{"type":"integer","description":"Pages whose content did not change (not embedded again)."},"skipped":{"type":"integer","description":"Pages left out (duplicates, too little text, the plan's page limit)."},"failed":{"type":"integer","description":"Pages that could not be read."},"removed":{"type":"integer","description":"Pages that disappeared from the site since the last sync."},"chunks":{"type":"integer"},"limitReached":{"type":"boolean","description":"The plan's page limit stopped the sync."},"startedAt":{"type":"string","format":"date-time"},"finishedAt":{"type":"string","format":"date-time"}}},"SourceStatus":{"type":"string","enum":["pending","syncing","ready","error"]},"SourceSyncedWebhookEvent":{"type":"object","required":["id","type","createdAt","workspaceId","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["source.synced"]},"createdAt":{"type":"string","format":"date-time"},"workspaceId":{"type":"string"},"data":{"type":"object","required":["site","source"],"properties":{"site":{"$ref":"#/components/schemas/WebhookSite"},"source":{"type":"object","required":["id","siteId","kind","title","status","error","stats","lastSyncedAt","nextSyncAt"],"properties":{"id":{"type":"string"},"siteId":{"type":"string"},"kind":{"type":"string","enum":["crawl","sitemap","file","qa","text"]},"title":{"type":"string"},"status":{"type":"string","enum":["ready","error"]},"error":{"type":["string","null"]},"stats":{"type":"object","additionalProperties":true,"description":"Pages found, indexed, unchanged, skipped, failed and removed, and chunks."},"lastSyncedAt":{"type":["string","null"],"format":"date-time"},"nextSyncAt":{"type":["string","null"],"format":"date-time"},"dashboardUrl":{"type":"string"}}}}}}},"StatsTotals":{"type":"object","additionalProperties":false,"required":["conversations","answers","measuredAnswers","groundedAnswers","leads","thumbsUp","thumbsDown"],"properties":{"conversations":{"type":"integer","description":"Visitors' conversations with at least one question, started in the period."},"answers":{"type":"integer","description":"Agent answers in visitors' conversations."},"measuredAnswers":{"type":"integer","description":"Answers that went through retrieval (greetings do not)."},"groundedAnswers":{"type":"integer","description":"Measured answers backed by the site's content."},"groundedRate":{"type":"number","minimum":0,"maximum":1,"description":"groundedAnswers / measuredAnswers; absent without measured answers."},"leads":{"type":"integer"},"thumbsUp":{"type":"integer"},"thumbsDown":{"type":"integer"}}},"TopQuestion":{"type":"object","additionalProperties":false,"required":["text","count","answered","unanswered","lastAskedAt","conversationId","siteId"],"properties":{"text":{"type":"string","description":"The wording visitors used most."},"count":{"type":"integer"},"answered":{"type":"integer","description":"Times the answer was grounded in the site's content."},"unanswered":{"type":"integer"},"lastAskedAt":{"type":"string","format":"date-time"},"conversationId":{"type":"string","description":"The newest conversation it was asked in."},"siteId":{"type":"string"}}},"WebhookDelivery":{"type":"object","additionalProperties":false,"required":["id","eventId","eventType","test","status","attempts","createdAt","payload"],"properties":{"id":{"type":"string","examples":["whd_8Kq2Lm5Vt7Xw1Rc4Np9H"]},"eventId":{"type":"string"},"eventType":{"type":"string","description":"The event type, or `test`."},"test":{"type":"boolean"},"status":{"$ref":"#/components/schemas/WebhookDeliveryStatus"},"attempts":{"type":"integer"},"nextAttemptAt":{"type":"string","format":"date-time"},"responseStatus":{"type":"integer","description":"The HTTP status of the last attempt (absent when there was no answer)."},"responseBody":{"type":"string","description":"The start of the endpoint's answer (1,000 characters)."},"error":{"type":"string"},"durationMs":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"lastAttemptAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"payload":{"type":"object","additionalProperties":true,"description":"The JSON body sent (a webhook event)."}}},"WebhookDeliveryList":{"type":"object","additionalProperties":false,"required":["deliveries"],"properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"nextCursor":{"type":"string"}}},"WebhookDeliveryStatus":{"type":"string","enum":["pending","retrying","delivered","failed"]},"WebhookEndpoint":{"type":"object","additionalProperties":false,"required":["id","url","description","events","enabled","secretHint","createdAt","updatedAt"],"properties":{"id":{"type":"string","examples":["whk_5Jd8Lq2Vt9Xw1Rc4Np7H"]},"url":{"type":"string"},"description":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"}},"enabled":{"type":"boolean"},"disabledReason":{"type":"string","enum":["manual","failing"],"description":"Why the endpoint is off; `failing` after 15 deliveries in a row failed for good."},"secretHint":{"type":"string","description":"The last characters of the signing secret."},"previousSecretExpiresAt":{"type":"string","format":"date-time","description":"After a rotation, until when the previous secret also signs."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookEndpointInput":{"type":"object","additionalProperties":false,"required":["url","events"],"properties":{"url":{"type":"string","maxLength":2048,"description":"A public https address."},"description":{"type":"string","maxLength":120},"events":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/WebhookEventType"}}}},"WebhookEndpointList":{"type":"object","additionalProperties":false,"required":["endpoints","events","entitled","maxEndpoints"],"properties":{"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"},"description":"Every event an endpoint can subscribe to."},"entitled":{"type":"boolean","description":"Whether the plan includes webhooks."},"minPlan":{"type":"string","description":"The cheapest plan with webhooks (when not entitled)."},"maxEndpoints":{"type":"integer"}}},"WebhookEndpointPatch":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":2048},"description":{"type":"string","maxLength":120},"events":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/WebhookEventType"}},"enabled":{"type":"boolean"}}},"WebhookEventType":{"type":"string","enum":["lead.created","lead.updated","conversation.closed","knowledge_gap.created","source.synced"]},"WebhookLead":{"type":"object","required":["id","siteId","conversationId","email","name","company","phone","note","consent","pageUrl","status","score","qualifiedAt","createdAt","preview"],"properties":{"id":{"type":"string"},"siteId":{"type":"string"},"conversationId":{"type":["string","null"]},"email":{"type":"string"},"name":{"type":["string","null"]},"company":{"type":["string","null"]},"phone":{"type":["string","null"]},"note":{"type":["string","null"]},"consent":{"type":"boolean"},"pageUrl":{"type":["string","null"]},"status":{"type":"string","enum":["new","contacted","archived"]},"score":{"type":["integer","null"],"description":"The Sales agent's score, 0–100."},"qualifiedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"preview":{"type":"boolean","description":"Left in the dashboard's preview, not by a visitor."},"dashboardUrl":{"type":"string"}}},"WebhookMessage":{"type":"object","required":["id","role","text","sources","createdAt"],"properties":{"id":{"type":"string"},"role":{"type":"string","enum":["visitor","agent"]},"text":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/AskSource"}},"createdAt":{"type":"string","format":"date-time"}}},"WebhookSite":{"type":"object","required":["id","name","origin"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"origin":{"type":"string"}}},"Workspace":{"type":"object","additionalProperties":false,"required":["id","name","planId","createdAt"],"properties":{"id":{"type":"string","examples":["wsp_8fK2nQ7xLm3Pz9Tb4Wv1"]},"name":{"type":"string"},"planId":{"type":"string","description":"Catalog plan id (packages/catalog).","examples":["free"]},"trialEndsAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"role":{"$ref":"#/components/schemas/Role"}}},"WorkspaceSuspension":{"type":"object","additionalProperties":false,"required":["suspended","contact"],"properties":{"suspended":{"type":"boolean"},"suspendedAt":{"type":"string","format":"date-time"},"contact":{"type":"string","description":"Where to write about it.","examples":["hello@asdk.com"]}}}},"responses":{"AnswerTimeout":{"description":"The answer took too long (type \"timeout\"); try again.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"Conflicts with the current state (types \"already-member\", \"last-owner\", \"limit-reached\", \"refresh-conflict\").","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"Authenticated but not allowed (types \"forbidden\", \"origin-not-allowed\", \"api-key-not-accepted\", \"email-mismatch\"; P36 \"insufficient-scope\", \"not-in-plan\", \"coming-soon\").","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"KnowledgeConflict":{"description":"Conflicts with the plan or the resource (types \"limit-reached\", \"site-exists\", \"not-supported\").","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"Not found, or not visible to the caller (type \"not-found\").","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Problem":{"description":"An error, as RFC 9457 problem details.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"RateLimited":{"description":"Too many requests (type \"rate-limited\"); retry after the Retry-After header.","headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"Missing, expired or revoked credentials (types \"unauthorized\", \"token-expired\", \"invalid-token\").","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unavailable":{"description":"The feature is not configured on this server (type \"unavailable\").","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"ValidationProblem":{"description":"Invalid input (type \"validation\"; `field` names the input).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":{"Cursor":{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` of the previous page.","schema":{"type":"string","maxLength":4096}},"InboxConversationId":{"name":"conversationId","in":"path","required":true,"description":"Conversation id (conv_…).","schema":{"type":"string","maxLength":64}},"LeadId":{"name":"leadId","in":"path","required":true,"description":"Lead id (lead_…).","schema":{"type":"string","maxLength":64}},"LeadStatusFilter":{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/LeadStatus"}},"PageLimit":{"name":"limit","in":"query","required":false,"description":"Items per page (default 50).","schema":{"type":"integer","minimum":1,"maximum":200}},"PreviewsFilter":{"name":"previews","in":"query","required":false,"description":"Conversations and leads from the dashboard's preview — include (default), exclude or only.","schema":{"type":"string","enum":["include","exclude","only"]}},"Search":{"name":"q","in":"query","required":false,"description":"Case-insensitive text search.","schema":{"type":"string","maxLength":200}},"SiteId":{"name":"siteId","in":"path","required":true,"description":"Site id (site_…).","schema":{"type":"string","maxLength":64}},"SourceId":{"name":"sourceId","in":"path","required":true,"description":"Knowledge source id (src_…).","schema":{"type":"string","maxLength":64}},"StatsDays":{"name":"days","in":"query","required":false,"description":"The period in days, today included (default 30).","schema":{"type":"integer","enum":[7,30,90]}},"StatsSiteId":{"name":"siteId","in":"query","required":false,"description":"Only this site of the workspace (site_…); all sites when absent.","schema":{"type":"string","maxLength":64}},"WebhookDeliveryHeader":{"name":"X-ASDK-Delivery","in":"header","required":true,"description":"The delivery id, the same on every retry (use it to drop duplicates).","schema":{"type":"string"}},"WebhookDeliveryId":{"name":"deliveryId","in":"path","required":true,"description":"Delivery id (whd_…).","schema":{"type":"string","maxLength":64}},"WebhookDeliveryLimit":{"name":"limit","in":"query","required":false,"description":"Deliveries per page (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},"WebhookEndpointId":{"name":"webhookId","in":"path","required":true,"description":"Webhook endpoint id (whk_…).","schema":{"type":"string","maxLength":64}},"WebhookEventHeader":{"name":"X-ASDK-Event","in":"header","required":true,"description":"The event type (also `type` in the body).","schema":{"type":"string"}},"WebhookSignature":{"name":"X-ASDK-Signature","in":"header","required":true,"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>`; during a secret rotation two `v1` values.","schema":{"type":"string"}},"WorkspaceId":{"name":"id","in":"path","required":true,"description":"Workspace id (wsp_…).","schema":{"type":"string","maxLength":64}}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Workspace API key (`asdk_live_…`), sent as a bearer token."}}}}