API Reference

Knowledge Base

Manage the AI knowledge base that powers automated responses across your channels.

Overview

The Knowledge Base stores information your AI agent uses when answering contact questions. The API supports all five content types — text, documents, voice transcriptions, product catalogs, and website scraping.

Type	Description	Processing
`text`	Structured text (FAQs, policies, instructions)	Synchronous
`document`	PDF, Word, Excel, TXT, CSV — AI extracts content	Synchronous
`voice`	Audio file — transcribed by OpenAI Whisper	Synchronous
`product_catalog`	Products via JSON array or CSV	Synchronous
`website`	Website crawl — async job, poll `/status`	Async

How the AI uses this in chat

Active entries of all types feed retrieval and grounding for AI agent replies on WhatsApp, Telegram, Instagram, and web chat. Extracted document and website text is embedded for semantic search; voice entries store transcripts; product catalogs supply structured fields and can reference linked media.

Together with the Media library, agents can attach images, videos, and files to outbound messages when your setup calls for it (for example catalog-linked assets or items you uploaded under Media). On inbound messages, audio is typically transcribed to text for the model, and images are analyzed so the assistant can reason about what the customer sent (channel and configuration dependent).

The KnowledgeBase object

{
  "id": 88,
  "title": "Return Policy",
  "type": "text",
  "description": "Customer return and refund policy",
  "business_description": "Used by the sales AI to answer returns-related questions",
  "status": "active",
  "embedding_updated_at": "2026-03-07T10:00:00.000000Z",
  "created_at": "2026-02-15T08:00:00.000000Z",
  "updated_at": "2026-03-07T10:00:00.000000Z"
}

Field	Type	Description
`id`	integer	Unique entry ID
`title`	string	Display name
`type`	string	`text`, `document`, `voice`, `product_catalog`, `website`
`description`	string\|null	Brief summary of the entry
`business_description`	string\|null	Context for how the AI should use this entry
`status`	string	`active` or `inactive`
`embedding_updated_at`	string\|null	When embeddings were last regenerated for AI search

List knowledge base entries

GET /api/v1/knowledge-base

Parameter	Type	Description
`type`	string	Filter by `text`, `document`, `voice`, `product_catalog`, `website`
`status`	string	`active`, `inactive`
`per_page`	integer	Max 100 (default 25)

Create a text entry

POST /api/v1/knowledge-base
Content-Type: application/json

Field	Type	Required	Notes
`title`	string	✓
`content`	string	✓	The knowledge text (the AI reads this)
`description`	string	No	Brief summary
`business_description`	string	No	Context for AI usage
`status`	string	No	`active` or `inactive` (default: `active`)

curl -X POST https://dashboard.skylightchat.com/api/v1/knowledge-base \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "30-Day Return Policy",
    "content": "We offer a full refund for any item returned within 30 days of purchase.",
    "description": "Customer return and refund policy",
    "business_description": "Used by the customer support AI to answer returns questions."
  }'

Returns 201 Created. Embeddings are generated asynchronously.

Upload a document

POST /api/v1/knowledge-base/document
Content-Type: multipart/form-data

Upload one or more files. The AI automatically extracts and structures the content. Supports PDF, DOCX, DOC, XLSX, CSV, and TXT up to 20 MB each.

Field	Type	Required	Notes
`title`	string	✓
`files[]`	file	✓	One or more files (PDF, DOCX, XLSX, CSV, TXT)
`description`	string	No
`business_description`	string	No
`status`	string	No	`active` or `inactive`

curl -X POST https://dashboard.skylightchat.com/api/v1/knowledge-base/document \
  -H "X-Api-Key: ••••••••••••" \
  -F "title=Product Manual" \
  -F "files[]=@/path/to/manual.pdf" \
  -F "business_description=Used to answer product-specific questions."

Response (201 Created)

{
  "success": true,
  "data": {
    "knowledge_base": { "id": 91, "title": "Product Manual", "type": "document" },
    "documents": [
      {
        "id": 12,
        "original_name": "manual.pdf",
        "file_type": "pdf",
        "processing_status": "completed",
        "extracted_content": "Chapter 1: Getting Started..."
      }
    ]
  }
}

Document processing statuses

Status	Meaning
`pending`	Queued
`processing`	AI is extracting content
`completed`	Content extracted successfully
`failed`	Extraction failed — see `processing_error`

Upload a voice note

POST /api/v1/knowledge-base/voice
Content-Type: multipart/form-data

Upload an audio file. Transcription is performed synchronously via OpenAI Whisper. Max 10 MB. Supports MP3, WAV, M4A, OGG, WEBM.

Field	Type	Required	Notes
`title`	string	✓
`audio_file`	file	✓	MP3, WAV, M4A, OGG, WEBM
`language`	string	No	ISO 639-1 code e.g. `ar`, `en` (default: auto-detect)
`description`	string	No
`business_description`	string	No
`status`	string	No	`active` or `inactive`

curl -X POST https://dashboard.skylightchat.com/api/v1/knowledge-base/voice \
  -H "X-Api-Key: ••••••••••••" \
  -F "title=CEO Welcome Message" \
  -F "audio_file=@/path/to/welcome.mp3" \
  -F "language=en"

Response (201 Created)

{
  "success": true,
  "data": {
    "knowledge_base": { "id": 92, "title": "CEO Welcome Message", "type": "voice" },
    "voice_note": {
      "id": 5,
      "transcription_status": "completed",
      "transcription": "مرحباً بك في نخيل. We are committed to delivering..."
    }
  }
}

Create a product catalog

POST /api/v1/knowledge-base/product-catalog
Content-Type: application/json  (or multipart/form-data for CSV)

Create a product catalog with products via a JSON array, a CSV file upload, or both.

Field	Type	Required	Notes
`title`	string	✓
`products`	array	*	JSON array of product objects
`csv_file`	file	*	CSV file (see columns below)
`description`	string	No
`business_description`	string	No
`status`	string	No	`active` or `inactive`

* At least one of products or csv_file is required.

Product object fields

Field	Type	Required	Notes
`product_name`	string	✓
`product_description`	string	No
`sku`	string	No
`price`	number	No
`currency`	string	No	Default: `USD`
`category`	string	No
`stock_quantity`	integer	No
`image_url`	string	No
`is_available`	boolean	No	Default: `true`

CSV column names: product_name (or name), description, sku, price, currency, category, stock (or stock_quantity), image_url

# JSON array
curl -X POST https://dashboard.skylightchat.com/api/v1/knowledge-base/product-catalog \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer 2026 Collection",
    "products": [
      {
        "product_name": "Linen Shirt",
        "product_description": "Breathable linen shirt for warm weather",
        "sku": "LS-001",
        "price": 49.99,
        "currency": "USD",
        "category": "Shirts",
        "stock_quantity": 120,
        "is_available": true
      }
    ]
  }'

# CSV upload
curl -X POST https://dashboard.skylightchat.com/api/v1/knowledge-base/product-catalog \
  -H "X-Api-Key: ••••••••••••" \
  -F "title=Summer 2026 Collection" \
  -F "csv_file=@/path/to/products.csv"

Response (201 Created)

{
  "success": true,
  "data": {
    "knowledge_base": { "id": 93, "title": "Summer 2026 Collection", "type": "product_catalog" },
    "products_created": 1,
    "products": [
      {
        "id": 41,
        "product_name": "Linen Shirt",
        "sku": "LS-001",
        "price": 49.99,
        "currency": "USD",
        "stock_quantity": 120,
        "is_available": true
      }
    ]
  }
}

Add products to an existing catalog

POST /api/v1/knowledge-base/{id}/products

Accepts the same products array and/or csv_file as above. Appends to the existing catalog.

Remove a product

DELETE /api/v1/knowledge-base/{id}/products/{product_id}

Returns 204 No Content.

Crawl a website

POST /api/v1/knowledge-base/website
Content-Type: application/json

Submit a website URL for crawling. The job is dispatched asynchronously — you receive a 202 Accepted immediately, then poll GET /knowledge-base/{id}/status to track progress.

Field	Type	Required	Notes
`title`	string	✓
`website_url`	string	✓	Valid URL
`sitemap_url`	string	No	Provide sitemap for faster discovery
`crawl_entire_site`	boolean	No	Default: `false`
`max_pages`	integer	No	1–100, default 10
`max_depth`	integer	No	1–5, default 2
`allowed_paths`	string	No	Comma-separated path prefixes to include e.g. `/docs,/help`
`excluded_paths`	string	No	Comma-separated path prefixes to skip e.g. `/blog,/careers`
`description`	string	No
`business_description`	string	No
`status`	string	No	`active` or `inactive`

curl -X POST https://dashboard.skylightchat.com/api/v1/knowledge-base/website \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "مركز مساعدة نخيل",
    "website_url": "https://help.nakheel.sa",
    "crawl_entire_site": true,
    "max_pages": 50,
    "excluded_paths": "/status,/login"
  }'

Response (202 Accepted)

{
  "success": true,
  "data": {
    "knowledge_base": { "id": 94, "title": "مركز مساعدة نخيل", "type": "website" },
    "website": {
      "id": 8,
      "website_url": "https://help.nakheel.sa",
      "crawl_status": "pending",
      "pages_crawled": 0,
      "total_pages_found": 0
    }
  }
}

Crawl status values

Status	Meaning
`pending`	Job is queued
`crawling`	Actively crawling pages
`completed`	All pages extracted
`partial`	Some pages extracted, some failed
`failed`	Crawl failed entirely — see `crawl_error`

Poll processing status

GET /api/v1/knowledge-base/{id}/status

Returns real-time progress for any entry type. Especially useful for website (async) and to verify document/voice processing completed.

Website status example

{
  "success": true,
  "data": {
    "id": 94,
    "title": "مركز مساعدة نخيل",
    "type": "website",
    "crawl_status": "crawling",
    "pages_crawled": 12,
    "total_pages": 50,
    "progress_pct": 24,
    "crawl_error": null,
    "last_crawled_at": null,
    "completed": false
  }
}

Document status example

{
  "success": true,
  "data": {
    "id": 91,
    "type": "document",
    "completed": true,
    "total": 2,
    "pending_count": 0,
    "failed_count": 0,
    "documents": [
      { "id": 12, "original_name": "manual.pdf", "processing_status": "completed" },
      { "id": 13, "original_name": "warranty.pdf", "processing_status": "completed" }
    ]
  }
}

Get an entry

GET /api/v1/knowledge-base/{id}

Returns the full entry with all associated content (documents, voice notes, products, or website details) depending on the type.

Update an entry

PUT /api/v1/knowledge-base/{id}

Field	Type	Notes
`title`	string
`content`	string	Only for `text` type. Changing content clears cached embeddings
`description`	string
`business_description`	string
`status`	string	`active` or `inactive`

Delete an entry

DELETE /api/v1/knowledge-base/{id}

Permanently removes the entry, all associated files, and its embeddings. Returns 204 No Content.

Deleting an active knowledge base entry may affect AI response quality immediately.

Web Chat

Monitor and manage live chat sessions from the embedded web widget.

Voice

Clone a voice and generate natural Arabic speech from text using the Voice API.