Skip to content
WebChat AI
HomeFeaturesHow it worksIntegrationsPricingDocs
WebChat AI

Build intelligent AI assistants trained on your website content.

Connect with us

Product

  • Features
  • How it works
  • Integrations
  • Pricing
  • Security

Resources

  • Documentation
  • API reference

Legal

  • Privacy Policy
  • Terms of Service

© 2026 WebChat AI. All rights reserved.

Get Started
OverviewQuickstart
Knowledge sourcesFile uploadsRAG & grounding
EmbedCustomizationConfigurationTesting
ConversationsAnalytics & usage
API referenceSecurityTroubleshooting
Changelog

Ready to launch?

Get Started Free
DocsDocumentationDeveloperAPI reference

Developer / REST API reference

REST API reference

The authoritative WebChat AI programmatic surface. All requests use JSON over HTTPS and execute with strict multi-tenant isolation.

Conventions & authentication

The WebChat AI API accepts JSON request payloads and returns JSON responses. Timestamps are formatted according to ISO 8601 (YYYY-MM-DDTHH:MM:SSZ).

  • Base URL: The API origin configured for your deployment. For dashboard clients, this is defined by NEXT_PUBLIC_API_URL.
  • Bearer Token (Browser Sessions): Passed in the Authorization: Bearer <jwt_access_token> header.
  • API Key (Server-to-Server): Passed in the X-API-Key: <secret_key> header for backend integration.
  • CSRF Protection: Mutating browser requests (POST, PATCH, DELETE) must supply the x-csrf-token header.

Common workflows & curl examples

1. Register an assistant (Website or Uploads)

Create a new assistant in website, files (upload-only), or mixed mode.

create-assistant.shbash
curl -X POST "https://api.webchat.ai/api/websites" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Docs Assistant",
    "url": "https://docs.acme.com",
    "source_mode": "mixed"
  }'

Response (201 Created):

website-created.jsonjson
{
  "id": "673f4a12bc90ef1234567890",
  "tenant_id": "tenant_98765",
  "name": "Acme Docs Assistant",
  "url": "https://docs.acme.com",
  "source_mode": "mixed",
  "status": "pending",
  "pages_indexed": 0,
  "widget_id": "wgt_ab8901cd",
  "knowledge_status": "empty",
  "knowledge_documents": 0,
  "knowledge_chunks": 0,
  "created_at": "2026-09-16T12:00:00Z",
  "updated_at": "2026-09-16T12:00:00Z"
}

2. Upload documents to Knowledge Base

Upload up to 5 files (.pdf, .docx, .md, .txt) totaling under 10 MB.

upload-documents.shbash
curl -X POST "https://api.webchat.ai/api/knowledge/websites/673f4a12bc90ef1234567890/documents/upload" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "files=@spec-sheet.pdf" \
  -F "files=@faq-guide.docx"

Response (201 Created):

upload-response.jsonjson
{
  "website_id": "673f4a12bc90ef1234567890",
  "uploaded": [
    {
      "id": "doc_101",
      "website_id": "673f4a12bc90ef1234567890",
      "file_name": "spec-sheet.pdf",
      "file_size_bytes": 1048576,
      "mime_type": "application/pdf",
      "status": "pending",
      "char_count": 0
    },
    {
      "id": "doc_102",
      "website_id": "673f4a12bc90ef1234567890",
      "file_name": "faq-guide.docx",
      "file_size_bytes": 262144,
      "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "status": "pending",
      "char_count": 0
    }
  ]
}

3. Trigger website crawl

Initiates crawler discovery starting from the registered root URL.

trigger-crawl.shbash
curl -X POST "https://api.webchat.ai/api/websites/673f4a12bc90ef1234567890/crawl" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (202 Accepted):

crawl-accepted.jsonjson
{
  "job_id": "crawl_89f029",
  "website_id": "673f4a12bc90ef1234567890",
  "status": "queued",
  "pages_discovered": 1,
  "pages_indexed": 0,
  "started_at": "2026-09-16T12:05:00Z"
}

HTTP status & error codes

Structured error codes returned in the standard response envelope: { error: { code, message } }.

Error codes by HTTP status
StatusCodes
400 Bad Request
INVALID_URLEMBEDDING_UNAVAILABLEEMBEDDING_INCOMPATIBLEINVALID_QUESTIONGENERATION_UNAVAILABLESPAM_REJECTEDDOCUMENT_TOO_LARGEUNSUPPORTED_MEDIA_TYPE
401 Unauthorized
INVALID_CREDENTIALSINVALID_TOKENTOKEN_EXPIREDTOKEN_REUSE_DETECTED
403 Forbidden
ACCOUNT_SUSPENDEDEMAIL_NOT_VERIFIEDFORBIDDENCSRF_FAILEDWIDGET_DISABLEDWIDGET_ORIGIN_NOT_ALLOWEDWIDGET_DOMAIN_NOT_CONFIGURED
404 Not Found
WEBSITE_NOT_FOUNDCRAWL_JOB_NOT_FOUNDDOCUMENT_NOT_FOUNDSESSION_NOT_FOUNDWIDGET_NOT_FOUNDAPI_KEY_NOT_FOUNDMESSAGE_NOT_FOUNDTENANT_NOT_FOUND
409 Conflict
EMAIL_ALREADY_EXISTSWEBSITE_ALREADY_EXISTSCRAWL_IN_PROGRESSWEBSITE_NOT_READY
422 Unprocessable
INSUFFICIENT_CONTENTVALIDATION_ERROR
429 Too Many Requests
AI_QUOTA_EXCEEDEDRATE_LIMIT_EXCEEDEDMESSAGE_LIMIT_REACHEDLIMIT_REACHED
500 Internal Error
PROVIDER_CONFIGURATION
502 Bad Gateway
EMBEDDING_FAILEDGENERATION_FAILEDPAYMENT_PROVIDER_ERROR
503 Unavailable
SERVICE_UNAVAILABLE

Health & System

Probes for container orchestration and uptime monitoring.

Health & System endpoints
MethodEndpoint PathDescription
GET/api/health/liveLightweight liveness probe (200).
GET/api/healthComprehensive health check reporting database and cache connectivity.
GET/api/health/readyReadiness probe for load balancers.

Websites & Assistants

Register assistants, configure ingestion modes, and trigger background crawls.

Websites & Assistants endpoints
MethodEndpoint PathDescription
POST/api/websitesRegister a new website or document-only assistant (201).
GET/api/websitesList all registered assistants for the authenticated tenant.
GET/api/websites/{websiteId}Get assistant metadata, crawl status, and knowledge chunk counts.
PATCH/api/websites/{websiteId}Update assistant name, root URL, or source mode.
DELETE/api/websites/{websiteId}Permanently remove an assistant and all associated documents/vectors.
POST/api/websites/{websiteId}/crawlTrigger an asynchronous web crawl job for the root URL (202).

Knowledge Base & Documents

Upload files (.pdf, .docx, .md, .txt), monitor chunking, and retry failed embeddings.

Knowledge Base & Documents endpoints
MethodEndpoint PathDescription
GET/api/knowledge/websites/{websiteId}/documentsList documents for an assistant with processing statuses and summaries.
POST/api/knowledge/websites/{websiteId}/documents/uploadUpload up to 5 documents (max 10 MB total) via multipart/form-data (201).
POST/api/knowledge/documents/{documentId}/retryRe-queue text extraction and embedding generation for a failed document.
DELETE/api/knowledge/documents/{documentId}Permanently delete a document, its extracted text, and vector embeddings.

Crawl Jobs

Track background sitemap discovery and page extraction jobs.

Crawl Jobs endpoints
MethodEndpoint PathDescription
GET/api/crawl-jobs/{jobId}Poll crawl job status, pages discovered, and pages indexed.
GET/api/crawl-jobs/{jobId}/streamServer-Sent Events (SSE) stream providing real-time crawl event updates.

Widget Configuration

Manage visual appearance, theme presets, font families, and domain allowlists.

Widget Configuration endpoints
MethodEndpoint PathDescription
GET/api/websites/{websiteId}/widgetFetch the active widget configuration and authoritative embed snippet.
PATCH/api/websites/{websiteId}/widgetUpdate theme preset, custom colors, font, bot branding, and allowed domains.

Conversations

Access visitor conversation history, source citations, and latency telemetry.

Conversations endpoints
MethodEndpoint PathDescription
GET/api/conversationsList visitor conversations with filtering by website, query, and status.
GET/api/conversations/{sessionId}Retrieve full conversation transcript, token metrics, and cited URLs.
DELETE/api/conversations/{sessionId}Permanently delete a visitor conversation session and messages.

Analytics & Reporting

Aggregated metrics, query frequency, response time histograms, and feedback.

Analytics & Reporting endpoints
MethodEndpoint PathDescription
GET/api/analytics/summary?days={n}Headline KPIs including total messages, sessions, response times, and costs.
GET/api/analytics/overview?days={n}Aggregated overview metrics comparing against prior window.
GET/api/analytics/timeseries?days={n}Daily message and active conversation timeseries data.
GET/api/analytics/top-websites?days={n}Activity rankings across registered assistants in your account.
GET/api/analytics/questions?days={n}&limit=10Most frequently asked visitor questions and satisfaction ratings.
GET/api/analytics/performance?days={n}Response time percentile breakdowns (p50, p90, p99).
GET/api/analytics/feedback?days={n}Sentiment breakdown of helpful vs unhelpful responses.

Feedback

Visitor sentiment scores and verbatim user comments.

Feedback endpoints
MethodEndpoint PathDescription
GET/api/feedbackList recent visitor feedback entries.
GET/api/feedback/summary?days={n}Compact positive vs negative satisfaction percentage summary.

Billing & Plans

Plan catalog, quota consumption, invoices, and checkout sessions.

Billing & Plans endpoints
MethodEndpoint PathDescription
GET/api/billing/plansList available subscription plans.
GET/api/billing/subscriptionGet current active subscription and payment history.
GET/api/billing/usageCurrent month usage vs plan limits.
POST/api/billing/checkoutCreate a Stripe/payment checkout session for tier upgrades (201).

API Keys

Generate and revoke API keys for headless server-to-server operations.

API Keys endpoints
MethodEndpoint PathDescription
POST/api/api-keysCreate a new scoped API key (201). Secret is displayed only once.
GET/api/api-keysList existing API keys with last-used timestamps.
DELETE/api/api-keys/{keyId}Instantly revoke an API key.

Building Headless Integrations

If you are building custom chat interfaces or automated ETL pipelines, generate an API Key in your dashboard settings and authenticate requests with the X-API-Key header.

Related documentation

Security & origin validation

Learn about domain allowlists, CSRF protection, and SSRF defense.

Read guide

Widget embed guide

Integrate the client widget on React, Next.js, or HTML sites.

Read guide

Troubleshooting guide

Common API error codes and debugging recipes.

Read guide

PreviousAnalytics & usageNext Security

Ready to build?

Register a website and get a live assistant in minutes.

Get Started Free